From 90cd685fde90827d2660251dbd240b17fb75cd65 Mon Sep 17 00:00:00 2001
From: Christian Hohnstaedt <christian@hohnstaedt.de>
Date: Mon, 19 Apr 2021 22:16:15 +0200
Subject: [PATCH] Improve documentation generation out-of-tree

Copy files (database-schema, COPYRIGHT, changelog)
to the destination directory

Name all documentation files and qthelp files explicitly
instead of using wildcards
---
 doc/.gitignore           |  2 ++
 doc/Makefile             | 52 +++++++++++++++++++++++++++-------------
 doc/conf.py.in           |  6 ++---
 doc/rst/changelog.rst    |  3 +--
 doc/rst/database.rst     |  2 +-
 doc/rst/introduction.rst |  2 +-
 6 files changed, 44 insertions(+), 23 deletions(-)

diff --git a/doc/.gitignore b/doc/.gitignore
index 968d230f..8be488cc 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -3,3 +3,5 @@ xca.1
 xca.1.gz
 xca_db_stat.1
 xca_db_stat.1.gz
+sphinx
+conf.py
diff --git a/doc/Makefile b/doc/Makefile
index b57be00a..7e358748 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -3,9 +3,18 @@ TOPDIR=..
 BUILD=..
 endif
 
-DELFILES=xca*.html xca.1.gz
+DELFILES=xca*.html xca.1.gz conf.py
+RST_FILES=arguments common-actions object-ids smartcard \
+	certificate-input database options step-by-step \
+	certificates index privatekey template changelog \
+	introduction requests commandline miscellaneous \
+	revocationlist
+
+SPHINX_FILES=$(patsubst %,sphinx/%.rst,$(RST_FILES))
 
 doc: xca.1.gz html/index.html qthelp/xca.qhc
+qthelpfiles=qthelp/*.html qthelp/xca.qhc qthelp/xca.qch
+
 include $(TOPDIR)/Rules.mak
 
 %.1.gz: %.1
@@ -15,32 +24,43 @@ include $(TOPDIR)/Rules.mak
 xca.1: xca.1.head xca.1.options xca.1.tail
 	cat $^ > $@
 
-html/index.html: static/bigcert.png conf.py
+html/index.html: sphinx/conf.py
 	@$(PRINT) "  HTML   [$(BASENAME)] $@"
-	$(DOCTOOL) $(DOCTOOLFLAGS) -b html -a -E -c . $(TOPDIR)/doc/rst html
+	$(ENABLE_DOC)$(DOCTOOL) -b html $(DOCTOOLFLAGS) sphinx html
 
-qthelp/xca.qhcp: static/bigcert.png conf.py
+qthelp/xca.qhcp: sphinx/conf.py
 	@$(PRINT) "  QTHELP [$(BASENAME)] $@"
-	$(DOCTOOL) $(DOCTOOLFLAGS) -b qthelp -a -E -c . $(TOPDIR)/doc/rst qthelp
+	$(ENABLE_DOC)$(DOCTOOL) -b qthelp $(DOCTOOLFLAGS) sphinx qthelp
 
 qthelp/xca.qhc: qthelp/xca.qhcp
 	@$(PRINT) "  QTHGEN [$(BASENAME)] $@"
-	$(HELPCOLL) $< -o $@
-
-static/bigcert.png: ../img/bigcert.png
-	mkdir -p static
-	cp $^ $@
+	$(ENABLE_DOC)$(HELPCOLL) $< -o $@
 
 install: $(doc)
 	$(ENABLE_DOC)install -m 755 -d $(DESTDIR)$(htmldir)
-	$(ENABLE_DOC)install -m 644 qthelp/*.html qthelp/xca.q* $(DESTDIR)$(htmldir)
+	$(ENABLE_DOC)install -m 644 $(qthelpfiles) $(DESTDIR)$(htmldir)
 	install -m 755 -d $(DESTDIR)$(mandir)/man1
 	install -m 644 *.1.gz $(DESTDIR)/$(mandir)/man1
 
-app: xca.html
+app: html/index.html
 	mkdir -p $(APPDIR)/Resources
-	install -m 644 xca*.html $(APPDIR)/Resources
-
-database_schema.sql: ../widgets/database_schema.cpp
-	sed 's/<<//; s/\\"/'"'"'/g; s,//,--,; s/"/ /g; s/\tschemas\[\(.*\)\].*/  -- Schema Version \1/; /^\t;$$/d' < $^ > $@
+	$(ENABLE_DOC)install -m 644 $(qthelpfiles) $(APPDIR)/Resources
 
+sphinx/conf.py: conf.py sphinx/database_schema.sql sphinx/changelog sphinx/COPYRIGHT sphinx/_static/bigcert.png $(SPHINX_FILES)
+	mkdir -p sphinx
+	cp $< $@
+sphinx/database_schema.sql: ../widgets/database_schema.cpp
+	mkdir -p sphinx
+	sed 's/<<//; s/\\"/'"'"'/g; s,//,--,; s/"/ /g; s/^[[:space:]]\+schemas\[\(.*\)\].*/  -- Schema Version \1/; /^\t$$/d' < $^ > $@
+sphinx/changelog: ../changelog
+	mkdir -p sphinx
+	cp $^ $@
+sphinx/COPYRIGHT: ../COPYRIGHT
+	@mkdir -p sphinx
+	cp $^ $@
+sphinx/_static/bigcert.png: ../img/bigcert.png
+	@mkdir -p sphinx/_static
+	cp $^ $@
+sphinx/%.rst: rst/%.rst
+	@mkdir -p sphinx
+	cp $^ $@
diff --git a/doc/conf.py.in b/doc/conf.py.in
index caac3b4f..8bafa560 100644
--- a/doc/conf.py.in
+++ b/doc/conf.py.in
@@ -34,12 +34,12 @@ extensions = [
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['@abs_srcdir@/_templates']
+templates_path = ['_templates']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['@abs_srcdir@/_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -58,4 +58,4 @@ html_theme_options = {
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['static']
+html_static_path = ['_static']
diff --git a/doc/rst/changelog.rst b/doc/rst/changelog.rst
index c3e7ec12..ac026c3b 100644
--- a/doc/rst/changelog.rst
+++ b/doc/rst/changelog.rst
@@ -2,5 +2,4 @@
 Changelog
 =========
 
-.. .. literalinclude:: ../../changelog
-.. include:: ../../changelog
+.. include:: changelog
diff --git a/doc/rst/database.rst b/doc/rst/database.rst
index 8e610669..06ff9135 100644
--- a/doc/rst/database.rst
+++ b/doc/rst/database.rst
@@ -39,6 +39,6 @@ shown to get the ID of the item in the database.
 Schema
 ------
 
-.. literalinclude:: ../database_schema.sql
+.. literalinclude:: database_schema.sql
    :language: sql
 
diff --git a/doc/rst/introduction.rst b/doc/rst/introduction.rst
index 1d154f73..2e7ed60b 100644
--- a/doc/rst/introduction.rst
+++ b/doc/rst/introduction.rst
@@ -65,5 +65,5 @@ PKCS#X : Public Key Cryptography Standards
 Copyright
 ---------
 
-  .. include:: ../../COPYRIGHT
+.. include:: COPYRIGHT