move manpage to sphinx

Use sphinx (sphinx-doc.org) to generate the UNIX man page from an
reStructuredText file instead of dealing with plain groff.

Use `meson setup -Dman-pages=enabled` to build the man page, and
`meson setup -Ddocumentation=enabled` to build the web documentation
explicitly. Both are enabled automatically if sphinx-build is found.

The man page will be installed as `<meson_mandir>/man8/flashrom.8` and
The html documentation in <meson_datadir>/doc/flashrom/html`.

The Makefile builds only the man-page format.

Increase the minimum version of meson from 0.53.0 to 0.57.0 to be
able to pass environment variables to the custom_target() command. That
is needed to pass the FLASHROM_VERSION to the documentation.

Change-Id: Iee9f1164c5913e47385e6f7d51dc7775a58b5a67
Signed-off-by: Thomas Heijligen <thomas.heijligen@secunet.com>
Reviewed-on: https://review.coreboot.org/c/flashrom/+/72619
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Anastasia Klimchuk <aklm@chromium.org>
Reviewed-by: Alexander Goncharov <chat@joursoir.net>

doc/conf.py

@@ -0,0 +1,41 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'flashrom'
+# copyright = '2023, The flashrom authors'
+author = 'The flashrom authors'
+release = os.getenv('FLASHROM_VERSION')
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+master_doc = 'index' # this is needed for old versions
+
+extensions = []
+
+#templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+#html_static_path = ['_static']
+
+
+
+# -- Options for manual page output --------------------------------------------
+man_make_section_directory = True
+man_show_urls = True
+man_pages = [
+    ('classic_cli_manpage', project, '', [], 8),
+]

doc/index.rst

@@ -0,0 +1,11 @@
+.. flashrom documentation master file, created by
+   sphinx-quickstart on Mon Jan 30 17:34:19 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. toctree::
+  :hidden:
+
+  classic_cli_manpage
+
+.. include:: ../README

doc/meson.build

@@ -0,0 +1,38 @@
+
+sphinx = find_program('sphinx-build', native : true, required : get_option('man-pages').enabled() or get_option('documentation').enabled())
+
+man_pages = [
+  'flashrom.8'
+]
+
+if sphinx.found()
+  if get_option('man-pages').auto() or get_option('man-pages').enabled()
+    man_outputs = []
+    foreach page : man_pages
+      man_outputs += 'man' + page.substring(-1)
+    endforeach
+
+    custom_target(
+      'man-pages',
+      command : [sphinx, '-b', 'man', '-q', '-d', '@PRIVATE_DIR@', '@CURRENT_SOURCE_DIR@', '@OUTDIR@'],
+      env     : {'FLASHROM_VERSION' : meson.project_version() },
+      build_always_stale : true, # sphinx handles rebuilds
+      output  : man_outputs,
+      install : true,
+      install_dir : get_option('mandir'),
+    )
+  endif
+
+  if get_option('documentation').auto() or get_option('documtation').enabled()
+    custom_target(
+      'documentation',
+      command : [sphinx, '-b', 'html', '-q', '-d', '@PRIVATE_DIR@', '@CURRENT_SOURCE_DIR@', '@OUTDIR@/html'],
+      env     : {'FLASHROM_VERSION' : meson.project_version() },
+      build_always_stale : true, # sphinx handles rebuilds
+      output  : 'html',
+      install : true,
+      install_dir : get_option('datadir') + '/doc/flashrom'
+    )
+  endif
+
+endif