Commit Graph

28 Commits

Author SHA1 Message Date
David Adam
cb46396b67 cmake: build executables by driving cargo directly
Drops the requirement for Corrosion, as almost none of its extensive features
are required.
2024-01-30 18:18:55 +08:00
Johannes Altmanninger
c0d1e41313 docs synopsis: add HTML highlighing and automate manpage markup
Recent synopsis changes move from literal code blocks to
[RST line blocks].  This does not translate well to HTML: it's not
rendered in monospace, so aligment is lost.  Additionally, we don't
get syntax highlighting in HTML, which adds differences to our code
samples which are highlighted.

We hard-wrap synopsis lines (like code blocks). To align continuation
lines in manpages we need [backslashes in weird places]. Combined with
the **, *, and `` markup, it's a bit hard to get the alignment right.

Fix these by moving synopsis sources back to code blocks and compute
HTML syntax highlighting and manpage markup with a custom Sphinx
extension.

The new Pygments lexer can tokenize a synopsis and assign the various
highlighting roles, which closely matches fish's syntax highlighing:
- command/keyword (dark blue)
- parameter (light blue)
- operator like and/or/not/&&/|| (cyan)
- grammar metacharacter (black)

For manpage output, we don't project the fish syntax highlighting
but follow the markup convention in GNU's man(1):

	bold text          type exactly as shown.
	italic text        replace with appropriate argument.

To make it easy to separate these two automatically, formalize that
(italic) placeholders must be uppercase; while all lowercase text is
interpreted literally (so rendered bold).
This makes manpages more consistent, see string-join(1) and and(1).

Implementation notes:
Since we want manpage formatting but Sphinx's Pygments highlighing
plugin does not support manpage output, add our custom "synopsis"
directive.  This directive parses differently when manpage output is
specified. This means that the HTML and manpage build processes must
not share a cache, because the parsed doctrees are cached.  Work around
this by using separate cache locations for build targets "sphinx-docs"
(which creates HTML) and "sphinx-manpages".  A better solution would
be to only override Sphinx's ManualPageBuilder but that would take a
bit more code (ideally we could override ManualPageWriter but Sphinx
4.3.2 doesn't really support that).

---

Alternative solution: stick with line blocks but use roles like
:command: or :option: (or custom ones). While this would make it
possible to produce HTML that is consistent with code blocks (by adding
a bit of CSS), the source would look uglier and is harder to maintain.
(Let's say we want to add custom formatting to the [|] metacharacters
in HTML.  This is much easier with the proposed patch.)

---

[RST line blocks]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks
[backslashes in weird places]: https://github.com/fish-shell/fish-shell/pull/8626#discussion_r782837750
2022-01-19 22:56:41 +08:00
ridiculousfish
ecaf455277 sphinx-build to use multiple processes
sphinx-build supports the -j option to use multiple processes. Start using
it. This reduces the time to build the docs on my Linux box from 11 seconds
to about 4.

Note this doesn't work on macOS since -j is ignored there (see sphinx-build
PR 6879).
2021-09-25 12:17:46 -07:00
Fabian Homborg
a36dbad3b8 cmake: Stop copying css files
custom no longer exists and pygments is just with the theme
2021-03-02 17:04:47 +01:00
ridiculousfish
f117addf7c Use lowercase CMake function names
This is a best practice to distinguish them from variables.
2020-03-14 16:11:35 -07:00
Aaron Gyes
85a0ca66e0 We no longer have two doc systems, move sphinx_doc_src back to doc_src 2020-02-19 17:00:35 -08:00
Johannes Altmanninger
b52d3d641e Fix clean build of sphinx-docs 2019-10-20 08:15:58 +02:00
Johannes Altmanninger
aa1bf9f277 sphinx: honor changes in static html assets
Also fix custom.css.
2019-10-19 14:52:24 +02:00
David Adam
8e0aa03c4a cmake: sphinx-manpages requires fish_indent for version number
Fixes issue .

Problem introduced in 3b8505bebe.
2019-09-21 16:32:24 +08:00
ridiculousfish
93cc99d6d0 Teach CMake to tell Sphinx where fish_indent is 2019-04-08 19:11:10 -07:00
ridiculousfish
5b2c741f6c Add fish_indent_lexer.py
This is a pygments lexer that shells out to fish_indent
2019-04-08 19:09:53 -07:00
David Adam
08fd8b6472 cmake: fix prebuilt documentation detection and installation 2019-03-04 22:06:09 +08:00
David Adam
73d9f80772 cmake: drop obsolete paths for prebuilt documentation 2019-02-28 22:04:54 +11:00
Fabian Homborg
3674efad0b Fix manpage directory
This installed files in man/ directly, instead of in man/man1/, so
they weren't installed.

See .
2019-02-25 21:16:42 +01:00
Fabian Homborg
0e82fb8c47 Install sphinx files
Sphinx put the files into sphinx-root, which wasn't being installed.

Instead, use user_doc again, which we already used before.

Belongs to .
2019-02-25 21:05:02 +01:00
ridiculousfish
4da38df43b Remove last vestiges of Doxygen from Docs.cmake 2019-02-24 19:02:39 -08:00
ridiculousfish
2ec33be90f CMake BUILD_DOCS option to look for sphinx instead of Doxygen 2019-02-24 18:58:25 -08:00
ridiculousfish
c46f02e01e Initial sphinx file import 2019-02-24 18:15:23 -08:00
David Adam
0f59e42802 [cmake] support prebuilt documentation in out-of-tree builds 2018-03-24 22:38:38 +08:00
David Adam
46e9bf86b8 [cmake] fix dependencies in documentation build
Closes two race conditions in parallel builds.
2018-03-24 22:38:38 +08:00
David Adam
072bbe7e5d [cmake] add doc target to ALL
Closes .
2018-03-24 22:38:38 +08:00
ridiculousfish
df4b03d859 Fix CMake documentation build path
This fixes a variety of issues related to building the documentation
with CMake. In particular it cleans up the dependency management and
fixes some issues where the documentation build was using generated
files from the source directory.
2018-03-05 12:13:34 -08:00
David Adam
56be045324 [cmake] copy shipped documentation files if they exist
Enables documentation in tarballs to be installed, even if Doxygen isn't
present.
2018-02-01 22:46:27 +08:00
David Adam
8875f0ad76 [cmake] make building documentation optional
Add a BUILD_DOCS option which is contingent on Doxygen being present,
and only build the documentation if this is enabled.
2018-01-14 21:16:11 +08:00
David Adam
8eb0608b00 [cmake] make build_lexicon_filter part of DocTargets only 2018-01-14 21:14:22 +08:00
ridiculousfish
d09210c08b [cmake] Untangle the CMake versioning
This untangles the CMake versioning issues (I hope) as discussed in .
Note most of the advice found on the Internet about how to inject git
versions into CMake is just wrong.

The behavior we want is to unconditionally run the script
build_tools/git_version_gen.sh at build time (i.e. when you invoke ninja or
make, and not when you invoke cmake, which is build system generation time).
This script is careful to only update the FISH-BUILD-VERSION-FILE if the
contents have changed, to avoid spurious rebuilding dependencies of
FISH-BUILD-VERSION-FILE. Assuming the git version hasn't changed, the script
will run, but not update FISH-BUILD-VERSION-FILE, and therefore
fish_version.o will not have to be rebuilt.

This might normally rebuild more than is necessary even if the timestamp is
not updated, because ninja computes the dependency chain ahead of time. But
Ninja also supports the 'restat' option for just this case, and CMake is rad
and exposes this via BYPRODUCTS. So mark FISH-BUILD-VERSION-FILE as a
byproduct and make the script always update a dummy file
(fish-build-version-witness.txt). Note this is the use case for which
BYPRODUCTS is designed.

We also have fish_version.cpp #include "FISH-BUILD-VERSION-FILE", and do a
semi-silly thing and make FISH-BUILD-VERSION-FILE valid C++ (so there's just
one version file). This means we have to filter out the quotes in other
cases..
2018-01-08 22:28:10 -08:00
David Adam
7faa6e773f cmake: add SED to build_lexicon_filter 2017-11-28 21:37:42 +08:00
David Adam
396faebc08 Move CMakeFiles to cmake
Makes in-tree (ie `cmake .`) builds work.
2017-11-17 16:21:55 +08:00