doc: generate latexpdf documentation

Gather main reference document to build a latexpdf file. Use a specific
RST index file for this purpose, that includes the other documents.

Signed-off-by: Xavier Delaruelle <[email protected]>

Author: xdelaruelle

.hunspell.en.dic

@@ -1301,3 +1301,4 @@ buildable
 Reproducibility
 rebase
 reproducibility
+latexpdf

NEWS.rst

@@ -30,6 +30,7 @@ Modules 5.6.1 (not yet released)
 * Doc: precise that no automatic path resolution is performed on
   :mfcmd:`prepend-path`, :mfcmd:`append-path` or :mfcmd:`remove-path`
   modulefile commands. (fix issue #597)
+* Doc: add way to build latexpdf documentation.
 
 .. _Furo: https://github.com/pradyunsg/furo
 

doc/Makefile

@@ -33,12 +33,14 @@ else
 ECHO_GEN2 = \#
 endif
 
-ALL_RST := $(wildcard $(SOURCE_DIR)/*.rst $(SOURCE_DIR)/cookbook/*.rst\
-	$(SOURCE_DIR)/design/*.rst)
+ALL_RST := $(filter-out $(SOURCE_DIR)/latex_index.rst, $(wildcard $(SOURCE_DIR)/*.rst\
+	$(SOURCE_DIR)/cookbook/*.rst $(SOURCE_DIR)/design/*.rst))
 ALL_TXT := $(patsubst $(SOURCE_DIR)/%,$(BUILD_DIR)/%,$(patsubst %.rst,%.txt,$(ALL_RST)))
 ALL_HTML := $(patsubst $(SOURCE_DIR)/%,$(BUILD_DIR)/%,$(patsubst %.rst,%.html,$(ALL_RST)))
 ALL_MAN := $(BUILD_DIR)/module.1 $(BUILD_DIR)/ml.1 $(BUILD_DIR)/envml.1\
 	$(BUILD_DIR)/modulefile.5
+ALL_TEX := $(BUILD_DIR)/latex/modules.tex
+ALL_PDF := $(BUILD_DIR)/latex/modules.pdf
 
 all: man txt
 
@@ -54,6 +56,8 @@ man: $(ALL_MAN)
 ifneq ($(builddoc),p)
 txt: $(ALL_TXT)
 html: $(ALL_HTML)
+latex: $(ALL_TEX)
+latexpdf: $(ALL_PDF)
 else
 # limit txt targets to documents that have been prebuilt
 txt: $(BUILD_DIR)/changes.txt $(BUILD_DIR)/MIGRATING.txt \
@@ -113,6 +117,14 @@ endif
 $(BUILD_DIR)/module.1: $(BUILD_DIR)/module.1.in
 	$(translate-in-script)
 
+$(BUILD_DIR)/latex/modules.tex: $(SOURCE_DIR)/version.py
+	$(ECHO_GEN2) $(ECHO_DIR_PREFIX)$@
+	$(SPHINXBUILD) $(SPHINXOPTS) -t latex -b latex "$(SOURCE_DIR)" "$(BUILD_DIR)/latex"
+
+$(BUILD_DIR)/latex/modules.pdf: $(BUILD_DIR)/latex/modules.tex
+	$(ECHO_GEN2) $(ECHO_DIR_PREFIX)$@
+	$(MAKE) -C "$(BUILD_DIR)/latex" all-pdf
+
 install: man txt
 	$(INSTALL_DIR) '$(DESTDIR)$(mandir)/man1' '$(DESTDIR)$(mandir)/man5'
 ifeq ($(docinstall),y)
@@ -162,4 +174,4 @@ V = 1
 endif
 # let verbose by default the install/clean/test and other specific non-build targets
 $(V).SILENT: ../version.inc $(SOURCE_DIR)/version.py $(ALL_HTML) $(ALL_TXT) \
-	$(BUILD_DIR)/module.1.in $(ALL_MAN)
+	$(BUILD_DIR)/module.1.in $(ALL_MAN) $(ALL_TEX) $(ALL_PDF)

doc/source/conf.py

@@ -42,12 +42,15 @@
 source_suffix = '.rst'
 
 # The master toctree document.
-master_doc = 'index'
+if 'latex' in tags:
+    master_doc = 'latex_index'
+else:
+    master_doc = 'index'
 
 # General information about the project.
 project = u'Modules'
-copyright = '1996-2025, Modules Contributors'
-author = ''
+author = 'Modules Contributors'
+copyright = f'1996-2025, {author}'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -102,7 +105,10 @@ def get_version_release_from_git():
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = []
+if 'latex' in tags:
+    exclude_patterns = []
+else:
+    exclude_patterns = ['latex_index.rst']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -196,6 +202,7 @@ def get_version_release_from_git():
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
+    ('latex_index', 'modules.tex', f'{project} documentation', author, 'manual'),
 ]
 
 

doc/source/latex_index.rst

@@ -0,0 +1,20 @@
+.. Latex Home page
+
+Environment Modules
+===================
+
+Introduction
+------------
+
+.. include:: index.rst
+   :start-line: 5
+
+.. include:: INSTALL.rst
+.. include:: INSTALL-win.rst
+.. include:: module.rst
+.. include:: modulefile.rst
+.. include:: ml.rst
+.. include:: envml.rst
+.. include:: MIGRATING.rst
+.. include:: NEWS.rst
+.. include:: changes.rst