Hi, this patch series wires up missing HTML-based documentation with Meson. This includes a couple of missing manpages, the user manual as well as the random set of articles that we have. It also starts to generate the indices for API docs and howtos so that the result is a complete set of HTML docs, same as with our Makefile. It also fixes a couple of smaller issues I found while working on the series. Notably missing yet is an integration with CI as well as sanity checks for any kind of missing docs in Meson. I'll work on this in a separate patch series once the initial CI integration as well as this patch series here have landed. Further missing is the generation of both info pages and a user manual PDF. I couldn't find any users of these anywhere in downstream distros, so I decided to not care for now until somebody complains. Changes in v2: - Change the base to 76cf4f61c8 (Merge https://github.com/j6t/git-gui, 2024-12-26). This is done to fix conflicts with in-flight topics and to pull in the CI setup. - Fix a typo. - Include another commit to auto-detect missing manpages in Meson both via Meson itself, but also via our Makefile. - Make the equivalent check in t/Makefile work with Dash. - Link to v1: https://lore.kernel.org/r/20241213-b4-pks-meson-docs-v1-0-0c7895952cd3@xxxxxx Thanks! Patrick --- Patrick Steinhardt (12): meson: wire up support for AsciiDoctor meson: properly wire up dependencies for our docs meson: fix generation of merge tools meson: generate HTML pages for all man page categories Documentation: inline user-manual.conf meson: generate user manual Documentation: refactor "api-index.sh" for out-of-tree builds Documentation: refactor "howto-index.sh" for out-of-tree builds meson: generate articles meson: install static files for HTML documentation t/Makefile: make "check-meson" work with Dash Documentation: wire up sanity checks for Meson Documentation/.gitignore | 1 + Documentation/Makefile | 24 ++- Documentation/asciidoc.conf.in | 10 ++ Documentation/{ => howto}/howto-index.sh | 2 +- Documentation/howto/meson.build | 62 ++++++++ Documentation/meson.build | 255 ++++++++++++++++++++++++++----- Documentation/technical/api-index.sh | 19 ++- Documentation/technical/meson.build | 66 ++++++++ Documentation/user-manual.conf | 11 -- meson_options.txt | 2 + t/.gitignore | 1 + t/Makefile | 12 +- 12 files changed, 402 insertions(+), 63 deletions(-) Range-diff versus v1: 1: e564c753c9 ! 1: 376ed916ce meson: wire up support for AsciiDoctor @@ Documentation/meson.build: manpages = { - input: meson.current_source_dir() / 'asciidoc.conf.in', - output: 'asciidoc.conf', - depends: [git_version_file], +- env: version_gen_environment, -) +if docs_backend == 'asciidoc' + asciidoc = find_program('asciidoc', required: true) @@ Documentation/meson.build: manpages = { + input: meson.current_source_dir() / 'asciidoc.conf.in', + output: 'asciidoc.conf', + depends: [git_version_file], ++ env: version_gen_environment, + ) + + asciidoc_common_options = [ @@ Documentation/meson.build: manpages = { + input: meson.current_source_dir() / 'asciidoctor-extensions.rb.in', + output: 'asciidoctor-extensions.rb', + depends: [git_version_file], ++ env: version_gen_environment, + ) + + asciidoc_common_options = [ 2: ce9bfd53f7 ! 2: 6c6e593fad meson: properly wire up dependencies for our docs @@ Documentation/meson.build: if docs_backend == 'asciidoc' + input: 'asciidoc.conf.in', output: 'asciidoc.conf', depends: [git_version_file], - ) + env: version_gen_environment, @@ Documentation/meson.build: elif docs_backend == 'asciidoctor' '@INPUT@', '@OUTPUT@', @@ Documentation/meson.build: elif docs_backend == 'asciidoctor' + input: 'asciidoctor-extensions.rb.in', output: 'asciidoctor-extensions.rb', depends: [git_version_file], - ) + env: version_gen_environment, @@ Documentation/meson.build: cmd_lists = [ documentation_deps += custom_target( command: [ 3: 905f220caa = 3: b962455582 meson: fix generation of merge tools 4: ff35b7433a ! 4: 32578c5cd2 meson: generate HTML pages for all man page categories @@ Commit message meson: generate HTML pages for all man page categories When generating HTML pages for our man pages we only generate them for - category 1 in MEson, which are the pages corresponding to our built-in + category 1 in Meson, which are the pages corresponding to our built-in commands. I cannot tell why I added this filter though: our Makefile installs all man pages, so a Meson-based build misses out on many of them. 5: bf8c278db5 ! 5: b704daf80c Documentation: inline user-manual.conf @@ Documentation/Makefile: manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $ technical/api-index.txt: technical/api-index-skel.txt \ ## Documentation/asciidoc.conf.in ## -@@ Documentation/asciidoc.conf.in: manmanual='Git Manual' - mansource='Git @GIT_VERSION@' - revdate='@GIT_DATE@' +@@ Documentation/asciidoc.conf.in: manmanual=Git Manual + mansource=Git @GIT_VERSION@ + revdate=@GIT_DATE@ +ifdef::doctype-book[] +[titles] 6: aaebbf0e94 = 6: 7eaf4f4267 meson: generate user manual 7: 1cc7d42a55 = 7: 52b9e4c34b Documentation: refactor "api-index.sh" for out-of-tree builds 8: 29fbda50a5 = 8: b9c8e5fe4d Documentation: refactor "howto-index.sh" for out-of-tree builds 9: cd7f5ee207 = 9: 1f724c113a meson: generate articles 10: d52f3db2bc = 10: acb6c5f370 meson: install static files for HTML documentation -: ---------- > 11: 2b893f7c0e t/Makefile: make "check-meson" work with Dash -: ---------- > 12: adf4835053 Documentation: wire up sanity checks for Meson --- base-commit: 76cf4f61c87855ebf0784b88aaf737d6b09f504b change-id: 20241212-b4-pks-meson-docs-2634bf3e7764
