[v2,00/12] meson: wire up missing HTML documentation

Message

Patrick Steinhardt Dec. 27, 2024, 1:59 p.m. UTC

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/[e-mail]

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