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>
2025-11-04 07:00:39 +01:00 · 2023-01-31 00:08:42 +01:00
parent fc533e2562
commit f4f2f3dd19
9 changed files with 1468 additions and 1870 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,7 @@
 *.d
 !Makefile.d/
 *.o
+/.doctrees
 /.features
 /.dependencies
 /.libdeps
@@ -12,6 +13,7 @@
 /flashrom.bash
 /libflashrom.a
 /libflashrom-doc/
+/man8

 /util/ich_descriptors_tool/ich_descriptors_tool
 /util/ich_descriptors_tool/ich_descriptors_tool.exe
--- a/23
+++ b/23
@@ -404,7 +404,6 @@ CLI_OBJS = cli_classic.o cli_output.o cli_common.o print.o
 # be obtained using util/getrevision.sh, which is the common case during development.
 -include versioninfo.inc
 VERSION ?= $(shell ./util/getrevision.sh --revision)
-MAN_DATE ?= $(shell ./util/getrevision.sh --date $(PROGRAM).8.tmpl 2>/dev/null)

 SCMDEF := -D'FLASHROM_VERSION="$(VERSION)"'

@@ -960,7 +959,7 @@ endif
 OBJS = $(CHIP_OBJS) $(PROGRAMMER_OBJS) $(LIB_OBJS)


-all: $(PROGRAM)$(EXEC_SUFFIX) $(PROGRAM).8
+all: $(PROGRAM)$(EXEC_SUFFIX) man8/$(PROGRAM).8
 ifeq ($(ARCH), x86)
 	@+$(MAKE) -C util/ich_descriptors_tool/ HOST_OS=$(HOST_OS) TARGET_OS=$(TARGET_OS)
 endif
@@ -1033,12 +1032,9 @@ libflashrom.a: $(OBJS)
 	$(AR) rcs $@ $^
 	$(RANLIB) $@

-$(PROGRAM).8.html: $(PROGRAM).8
-	@groff -mandoc -Thtml $< >$@
-
-$(PROGRAM).8: $(PROGRAM).8.tmpl
-	@# Add the man page change date and version to the man page
-	@sed -e 's#.TH FLASHROM 8 .*#.TH FLASHROM 8 "$(MAN_DATE)" "$(VERSION)" "$(MAN_DATE)"#' <$< >$@
+SPHINXBUILD ?= sphinx-build
+man8/$(PROGRAM).8: doc/*
+	@FLASHROM_VERSION=$(VERSION) $(SPHINXBUILD) -b man doc .

 $(PROGRAM).bash: util/$(PROGRAM).bash-completion.tmpl
 	@# Add to the bash completion file a list of enabled programmers.
@@ -1051,16 +1047,16 @@ strip: $(PROGRAM)$(EXEC_SUFFIX)
 # This includes all frontends and libflashrom.
 # We don't use EXEC_SUFFIX here because we want to clean everything.
 clean:
-	rm -f $(PROGRAM) $(PROGRAM).exe libflashrom.a $(filter-out Makefile.d, $(wildcard *.d *.o platform/*.d platform/*.o)) \
-		$(PROGRAM).8 $(PROGRAM).8.html $(PROGRAM).bash $(BUILD_DETAILS_FILE)
+	rm -rf $(PROGRAM) $(PROGRAM).exe libflashrom.a $(filter-out Makefile.d, $(wildcard *.d *.o platform/*.d platform/*.o)) \
+		man8 .doctrees $(PROGRAM).bash $(BUILD_DETAILS_FILE)
 	@+$(MAKE) -C util/ich_descriptors_tool/ clean

-install: $(PROGRAM)$(EXEC_SUFFIX) $(PROGRAM).8 $(PROGRAM).bash
+install: $(PROGRAM)$(EXEC_SUFFIX) man8/$(PROGRAM).8 $(PROGRAM).bash
 	mkdir -p $(DESTDIR)$(PREFIX)/sbin
 	mkdir -p $(DESTDIR)$(MANDIR)/man8
 	mkdir -p $(DESTDIR)$(BASHCOMPDIR)
 	$(INSTALL) -m 0755 $(PROGRAM)$(EXEC_SUFFIX) $(DESTDIR)$(PREFIX)/sbin
-	$(INSTALL) -m 0644 $(PROGRAM).8 $(DESTDIR)$(MANDIR)/man8
+	$(INSTALL) -m 0644 man8/$(PROGRAM).8 $(DESTDIR)$(MANDIR)/man8
 	$(INSTALL) -m 0644 $(PROGRAM).bash $(DESTDIR)$(BASHCOMPDIR)

 libinstall: libflashrom.a include/libflashrom.h
@@ -1069,13 +1065,12 @@ libinstall: libflashrom.a include/libflashrom.h
 	mkdir -p $(DESTDIR)$(PREFIX)/include
 	$(INSTALL) -m 0644 include/libflashrom.h $(DESTDIR)$(PREFIX)/include

-_export: $(PROGRAM).8
+_export: man8/$(PROGRAM).8
 	@rm -rf "$(EXPORTDIR)/flashrom-$(RELEASENAME)"
 	@mkdir -p "$(EXPORTDIR)/flashrom-$(RELEASENAME)"
 	@git archive HEAD | tar -x -C "$(EXPORTDIR)/flashrom-$(RELEASENAME)"
 #	Generate versioninfo.inc containing metadata that would not be available in exported sources otherwise.
 	@echo "VERSION = $(VERSION)" > "$(EXPORTDIR)/flashrom-$(RELEASENAME)/versioninfo.inc"
-	@echo "MAN_DATE = $(MAN_DATE)" >> "$(EXPORTDIR)/flashrom-$(RELEASENAME)/versioninfo.inc"
 #	Restore modification date of all tracked files not marked 'export-ignore' in .gitattributes.
 #	sed is required to filter out file names having the attribute set.
 #	The sed program saves the file name in the hold buffer and then checks if the respective value is 'set'.
--- a/doc/classic_cli_manpage.rst
+++ b/doc/classic_cli_manpage.rst
--- a/doc/conf.py
+++ b/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),
+]
--- a/doc/index.rst
+++ b/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
--- a/doc/meson.build
+++ b/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
--- a/flashrom.8.tmpl
+++ b/flashrom.8.tmpl
--- a/meson.build
+++ b/meson.build
@@ -1,7 +1,7 @@
 project('flashromutils', 'c',
  version : run_command('util/getversion.sh', '--version', check : true).stdout().strip(),
  license : 'GPL-2.0',
-  meson_version : '>=0.53.0',
+  meson_version : '>=0.57.0',
  default_options : [
    'warning_level=2',
    'c_std=c99',
@@ -11,6 +11,8 @@ project('flashromutils', 'c',
  ],
 )

+subdir('doc')
+
 # libtool versioning
 lt_current = '1'
 lt_revision = '0'
@@ -621,17 +623,6 @@ pkgg.generate(
  description : 'library to interact with flashrom',
 )

-config_manfile = configuration_data()
-config_manfile.set('VERSION', version)
-config_manfile.set('MAN_DATE', run_command('util/getversion.sh', '--man-date', check : true).stdout().strip())
-configure_file(
-  input : 'flashrom.8.tmpl',
-  output : 'flashrom.8',
-  configuration : config_manfile,
-  install: true,
-  install_dir: join_paths(get_option('mandir'), 'man8'),
-)
-
 if get_option('classic_cli').auto() or get_option('classic_cli').enabled()
  classic_cli = executable(
    'flashrom',
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -18,3 +18,5 @@ option('programmer', type : 'array', value : ['auto'], choices : [
        'rayer_spi', 'realtek_mst_i2c_spi', 'satamv', 'satasii', 'serprog',  'stlinkv3_spi', 'usbblaster_spi',
 ], description: 'Active programmers')
 option('llvm_cov', type : 'feature', value : 'disabled', description : 'build for llvm code coverage')
+option('man-pages', type : 'feature', value : 'auto', description : 'build the man-page for classic_cli')
+option('documentation', type : 'feature', value : 'auto', description : 'build the html documentation')