Update documentation build/installation

Jay Berkenbilt
1 parent eb20b4d0
Showing 18 changed files with 76 additions and 112 deletions
.github/workflows/main.yml
.gitignore
Makefile
README-maintainer
README.md
TODO
build-scripts/build-mac
build-scripts/build-windows
build-scripts/make-distfiles → build-scripts/prebuild
cSpell.json
make/installwin.mk
make/libtool.mk
manual/build.mk
manual/fix-qdf.1.in
manual/installation.rst
manual/qpdf.1.in
manual/release-notes.rst
manual/zlib-flate.1.in
@@ -19,21 +19,20 @@ on:
     # have reliable testing.
     - cron: '12 4 * * 5'
 jobs:
-  Distfiles:
-    # Generate distfiles.zip, which is a prerequisite for the mac and
-    # Windows builds. Only the mac and Windows builds actually "need"
-    # it, but declaring all the jobs to need it forces it to run
-    # first.
+  Prebuild:
+    # Run steps that are needed by the Windows build but are easier to
+    # build on Linux. Although only the Windows builds need this,
+    # other jobs depend on it to force it to run early.
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - name: 'Create distfiles.zip'
-        run: build-scripts/make-distfiles
+      - name: 'Run pre-build steps'
+        run: build-scripts/prebuild
       - name: 'Upload extra distribution files'
         uses: actions/upload-artifact@v1
         with:
-          name: distfiles
-          path: distfiles.zip
+          name: doc
+          path: doc.zip
       - name: 'Upload external libs'
         uses: actions/upload-artifact@v1
         with:
@@ -52,7 +51,7 @@ jobs:
           path: distribution
   Windows:
     runs-on: windows-latest
-    needs: Distfiles
+    needs: Prebuild
     strategy:
       fail-fast: false
       max-parallel: 4
@@ -64,10 +63,10 @@ jobs:
         shell: bash
         run: git config --global core.autocrlf input
       - uses: actions/checkout@v2
-      - name: 'Download distribution files'
+      - name: 'Download documentation'
         uses: actions/download-artifact@v2
         with:
-          name: distfiles
+          name: doc
           path: .
       - name: 'Download external libs'
         uses: actions/download-artifact@v2
@@ -84,13 +83,9 @@ jobs:
           path: distribution
   macOS:
     runs-on: macos-latest
-    needs: Distfiles
+    needs: Prebuild
     steps:
       - uses: actions/checkout@v2
-      - name: 'Download distribution files'
-        uses: actions/download-artifact@v2
-        with:
-          name: distfiles
       - name: 'Download external libs'
         uses: actions/download-artifact@v2
         with:
@@ -100,7 +95,7 @@ jobs:
         run: build-scripts/build-mac
   AppImage:
     runs-on: ubuntu-latest
-    needs: Distfiles
+    needs: Prebuild
     steps:
       - uses: actions/checkout@v2
       - name: 'Build AppImage'
@@ -112,21 +107,21 @@ jobs:
           path: distribution
   Linux32:
     runs-on: ubuntu-latest
-    needs: Distfiles
+    needs: Prebuild
     steps:
       - uses: actions/checkout@v2
       - name: 'Linux 32-bit'
         run: build-scripts/build-linux32
   Fuzzers:
     runs-on: ubuntu-latest
-    needs: Distfiles
+    needs: Prebuild
     steps:
       - uses: actions/checkout@v2
       - name: 'Build Fuzzer'
         run: build-scripts/build-fuzzer
   Sanitizers:
     runs-on: ubuntu-latest
-    needs: Distfiles
+    needs: Prebuild
     steps:
       - uses: actions/checkout@v2
       - name: 'Sanitizer Tests'
@@ -5,8 +5,8 @@ autoconf.mk
 autom4te.cache/
 config.log
 config.status
-distfiles.zip
 doc
+doc.zip
 examples/build/
 external-libs
 fuzz/build/
@@ -97,23 +97,16 @@ $(foreach B,$(BUILD_ITEMS),$(eval \
   clean_$(B): ; \
 	$(RM) -r $(B)/$(OUTPUT_DIR)))
  
-DISTFILES = doc/qpdf-manual.html doc/qpdf-manual.pdf
-distfiles.zip: $(DISTFILES)
-	$(RM) distfiles.zip
-	zip -r distfiles.zip $(DISTFILES) doc/_static
-
 distclean: clean
 	$(RM) -r autoconf.mk autom4te.cache config.log config.status libtool
 	$(RM) libqpdf/qpdf/qpdf-config.h
 	$(RM) manual/html.xsl
 	$(RM) manual/print.xsl
-	$(RM) doc/*.1
 	$(RM) libqpdf.pc libqpdf.map
  
 maintainer-clean: distclean
-	$(RM) doc/qpdf-manual.*
 	$(RM) -r install-mingw* install-msvc* external-libs
-	$(RM) distfiles.zip
+	$(RM) -rf doc
  
 .PHONY: $(TEST_TARGETS)
  
@@ -119,7 +119,7 @@ RELEASE PREPARATION
   git --no-pager grep -i -n -P "copyright.*$(expr $(date +%Y) - 1).*berkenbilt"
  
   Also update the copyright in these places:
-  * manual
+  * manual/conf.py
   * debian package -- search for copyright.*berkenbilt in debian/copyright
   * qtest-driver, TestDriver.pm in qtest source
  
@@ -210,14 +210,12 @@ RELEASE PREPARATION
   * Make sure version numbers are consistent in the following locations:
     * configure.ac
     * libqpdf/QPDF.cc
-    * manual/qpdf-manual.xml
+    * manual/conf.py
     * qpdf/qpdf.cc
     `make_dist` verifies this consistency.
  
   * Update release notes in manual. Look at diffs and ChangeLog.
-    Update release date in `manual/qpdf-manual.xml`. Remember to
-    ensure that the entities at the top of the document are consistent
-    with the release notes for both version and release date.
+    Update release date in `manual/release-notes.rst`.
  
   * Add a release entry to ChangeLog: "x.y.z: release"
  
@@ -327,7 +325,7 @@ Template for release notes:
 ```
 This is qpdf version x.y.z. (Brief description)
  
-For a full list of changes from previous releases, please see the [release notes](http://qpdf.sourceforge.net/files/qpdf-manual.html#release-notes). See also [README-what-to-download](./README-what-to-download.md) for details about the available source and binary distributions.
+For a full list of changes from previous releases, please see the [release notes](https://qpdf.sourceforge.io/doc/html/release-notes.html). See also [README-what-to-download](./README-what-to-download.md) for details about the available source and binary distributions.
 ```
  
 # Publish release
@@ -348,7 +346,7 @@ rsync -vrlcO ./ jay_berkenbilt,qpdf@frs.sourceforge.net:/home/frs/project/q/qp/q
  
 (cd /tmp; mkdir -p z; cd z; \
  tar xf ~/Q/storage/releases/qpdf/qpdf/$version/qpdf-$version.tar.gz qpdf-$version/doc; \
- scp -p qpdf-$version/doc/qpdf-* jay_berkenbilt,qpdf@frs.sourceforge.net:htdocs/files/)
+ rsync -avx --delete --force --exclude '*.1' qpdf-$version/doc/ jay_berkenbilt,qpdf@frs.sourceforge.net:htdocs/doc/)
  
 * Upload the debian package and Ubuntu ppa backports.
  
@@ -68,7 +68,7 @@ The PDF file format used to rely on RC4 for encryption. Using 256-bit keys alway
  
 # Building from a pristine checkout
  
-When building qpdf from a pristine checkout from version control, generated documentation files are not present. You may either generate them (by passing `--enable-doc-maintenance` to `./configure` and satisfying the extra build-time dependencies) or obtain them from a released source package, which includes them. If you want to grab just the files that are in the source distribution but not in the repository, extract a source distribution in a temporary directory, and run `make CLEAN=1 distfiles.zip`. This will create a file called `distfiles.zip`, which can you can extract in a checkout of the source repository. This step is optional unless you are running make install and want the html and PDF versions of the documentation to be installed.
+When building qpdf from a pristine checkout from version control, generated HTML and PDF documentation files are not present. You don't need them unless you are going to run `make install` and want the documentation to be installed. If you want them, you can either extract the `doc` directory from a source distribution, or you can satisfy the additional requirements for building documentation and pass `--enable-doc-maintenance` to `./configure`.
  
 # Building from source distribution on UNIX/Linux
  
 Next
 ====
  
-* Add spell check to CI
-
 * High-level API/doc overhaul: #593
  
 * Refactor test_driver.cc so that runtest is not one huge function.
@@ -19,24 +17,6 @@ Next
   thrown when an uninitialized trailer is accessed provides useful
   information. Test from the C API as well as the C++ API.
  
-Doc conversion
-==============
-
-Before release:
-
-* Figure out what to do about the fact that the release notes are now
-  at #release-notes instead of #ref.release-notes. This invalidates
-  the link in all previous release announcements, but there's not much
-  I can do about, and it doesn't seem worth fixing. Maybe mention it
-  somewhere?
-* README-maintainer: Fix installation of documentation to website
-
-Soon:
-
-* :ref: -- would be nice if it were suitable for printed documentation
-* Decide about readthedocs; if using, with multiple versions/latest
-* Generate stuff (options, code samples, etc.) as needed
-
 Documentation
 =============
  
@@ -52,6 +32,8 @@ Documentation
 * See #530 -- add an appendix explaining PDF encryption in general
   plus how it's handled by qpdf. Or maybe this should go on the wiki.
  
+* Decide about readthedocs including supporting multiple released
+  versions of the docs and docs from main.
  
 Document-level work
 ===================
@@ -8,9 +8,6 @@ cd jpeg-*
 make -k
 sudo make install
 cd ..
-if [ -f distfiles/distfiles.zip ]; then
-    unzip distfiles/distfiles.zip
-fi
 ./configure --enable-werror --enable-show-failed-test-output
 make -j$(nproc) -k
 make -k check
@@ -20,7 +20,7 @@ if [[ $tool == mingw ]]; then
 elif [[ $tool == msvc ]]; then
     cl
 fi
-unzip distfiles.zip
+unzip doc.zip
 unzip qpdf-external-libs-bin.zip
 cwd=`pwd`
 PATH=$cwd/libqpdf/build:$PATH
@@ -7,5 +7,6 @@ sudo apt-get -y install \
    python3-pip texlive-latex-extra latexmk inkscape imagemagick
 pip3 install sphinx
 ./configure --enable-doc-maintenance
-make -j$(nproc) distfiles.zip
+make -j$(nproc) build_manual
+zip -r doc.zip doc/*html doc/*.pdf
 build-scripts/download-external-libs
@@ -11,6 +11,7 @@
     "afdh",
     "afdhph",
     "ageneration",
+    "agogo",
     "aitems",
     "annots",
     "aobjid",
@@ -73,6 +74,7 @@
     "dctdecode",
     "decrypter",
     "deduplicating",
+    "deps",
     "destdir",
     "dests",
     "devel",
@@ -80,7 +82,6 @@
     "diffutils",
     "directpagerefcount",
     "distclean",
-    "distfiles",
     "ditems",
     "docbook",
     "docdir",
@@ -299,6 +300,7 @@
     "pluggable",
     "pngify",
     "poppler",
+    "prebuild",
     "precheck",
     "prepended",
     "prepending",
@@ -17,11 +17,12 @@ installwin: all
 	cp qpdf/$(OUTPUT_DIR)/fix-qdf.exe $(DEST)/bin
 	cp include/qpdf/*.h $(DEST)/include/qpdf
 	cp include/qpdf/*.hh $(DEST)/include/qpdf
-	if [ -f doc/qpdf-manual.html ]; then \
-	    mkdir $(DEST)/doc/_static; \
-	    cp doc/qpdf-manual.html $(DEST)/doc; \
-	    cp doc/_static/* $(DEST)/doc/_static; \
-	fi
 	if [ -f doc/qpdf-manual.pdf ]; then \
 	    cp doc/qpdf-manual.pdf $(DEST)/doc; \
 	fi
+	if [ -d doc/html ]; then \
+	    cp -r doc/html $(DEST)/doc; \
+	fi
+	if [ -d doc/singlehtml ]; then \
+	    cp -r doc/singlehtml $(DEST)/doc; \
+	fi
@@ -121,8 +121,6 @@ install-libs: build_libqpdf
 # NOTE: If installing any new executables, remember to update the
 # lambda layer code in build-scripts/build-appimage.
  
-# NOTE: See comments in manual/build.mk about html documentation.
-
 # Ensure that installwin in make/installwin.mk is consistent with
 # this.
  
@@ -139,12 +137,13 @@ install: all install-libs
 	$(LIBTOOL) --mode=install ./install-sh \
 		qpdf/$(OUTPUT_DIR)/fix-qdf \
 		$(DESTDIR)$(bindir)/fix-qdf
-	if [ -f doc/qpdf-manual.html ]; then \
-		./mkinstalldirs -m 0755 $(DESTDIR)$(docdir)/_static; \
-		./install-sh -m 0644 doc/qpdf-manual.html $(DESTDIR)$(docdir); \
-		./install-sh -m 0644 doc/_static/* $(DESTDIR)$(docdir)/_static; \
-	fi
 	if [ -f doc/qpdf-manual.pdf ]; then \
 		./install-sh -m 0644 doc/qpdf-manual.pdf $(DESTDIR)$(docdir); \
 	fi
+	if [ -d doc/html ]; then \
+		cp -r doc/html $(DESTDIR)/$(docdir); \
+	fi
+	if [ -d doc/singlehtml ]; then \
+		cp -r doc/singlehtml $(DESTDIR)/$(docdir); \
+	fi
 	./install-sh -m 0644 doc/*.1 $(DESTDIR)$(mandir)/man1
@@ -8,10 +8,10 @@ PDF_TARGET := $(PDF_OUT)/qpdf.pdf
  
 TARGETS_manual := doc/qpdf.1 doc/fix-qdf.1 doc/zlib-flate.1
 ifeq ($(BUILD_HTML),1)
-TARGETS_manual += doc/qpdf-manual.html $(HTML_TARGET)
+TARGETS_manual += $(HTML_TARGET) $(S_HTML_TARGET)
 endif
 ifeq ($(BUILD_PDF),1)
-TARGETS_manual += doc/qpdf-manual.pdf
+TARGETS_manual += $(PDF_TARGET)
 endif
  
 MANUAL_DEPS = $(wildcard manual/*.rst) manual/conf.py
@@ -22,33 +22,20 @@ MANUAL_DEPS = $(wildcard manual/*.rst) manual/conf.py
 # the error "_pickle.UnpicklingError: pickle data was truncated"
 $(HTML_TARGET): $(MANUAL_DEPS)
 	$(SPHINX) -M html manual $(DOC_OUT) -W
+	mkdir -p doc
+	rm -rf doc/html
+	cp -r $(DOC_OUT)/html doc
  
 $(S_HTML_TARGET): $(MANUAL_DEPS) | $(HTML_TARGET)
 	$(SPHINX) -M singlehtml manual $(DOC_OUT) -W
+	mkdir -p doc
+	rm -rf doc/singlehtml
+	cp -r $(DOC_OUT)/singlehtml doc
  
 $(PDF_TARGET): $(MANUAL_DEPS) | $(S_HTML_TARGET) $(HTML_TARGET)
 	$(SPHINX) -M latexpdf manual $(DOC_OUT) -W
-
-# This depends on sphinx-build's singlehtml target creating index.html
-# and a _static directory. If that changes, this code has to be
-# adjusted. It will also be necessary to adjust the install target in
-# make/libtool.mk.
-doc/qpdf-manual.html: $(S_HTML_TARGET)
-	mkdir -p doc
-	@if [ "$(shell find $(S_HTML_OUT)/ -mindepth 1 -type d -print)" != \
-             "$(S_HTML_OUT)/_static" ]; then \
-	    echo "***"; \
-	    echo Expected only directory in $(S_HTML_OUT) to be _static; \
-	    echo "***"; \
-	    false; \
-	fi
-	cp $< $@
-	mkdir -p doc/_static
-	cp -p $(S_HTML_OUT)/_static/* doc/_static
-
-doc/qpdf-manual.pdf: $(PDF_TARGET)
 	mkdir -p doc
-	cp $< $@
+	cp $(PDF_TARGET) doc/qpdf-manual.pdf
  
 doc/%.1: manual/%.1.in
 	mkdir -p doc
@@ -14,5 +14,5 @@ the same file with stream lengths, cross-reference table entries, and
 object stream offset tables regenerated.
 .PP
 For details about fix-qdf and about PDF files in QDF mode, please see
-the qpdf manual, which can be found in @docdir@/qpdf-manual.html or
+the qpdf manual, which can be found in @docdir@/html/index.html or
 @docdir@/qpdf-manual.pdf.
@@ -64,7 +64,7 @@ Pre-built documentation is distributed with qpdf, so you should
 generally not need to rebuild the documentation. In order to build the
 documentation from source, you need to install `Sphinx
 <https://sphinx-doc.org>`__. To build the PDF version of the
-documentation, you need `pdflatex`, `latexmk`, and a fairly complete
+documentation, you need ``pdflatex``, ``latexmk``, and a fairly complete
 LaTeX installation. Detailed requirements can be found in the Sphinx
 documentation.
  
@@ -16,4 +16,4 @@ useful primarily to PDF developers.
 .PP
 For a summary of qpdf's options, please run
 \fBqpdf \-\-help\fR.  A complete manual can be found in
-@docdir@/qpdf-manual.html or @docdir@/qpdf-manual.pdf.
+@docdir@/html/index.html or @docdir@/qpdf-manual.pdf.
@@ -7,6 +7,25 @@ For a detailed list of changes, please see the file
 :file:`ChangeLog` in the source distribution.
  
 10.5.0: XXX Month dd, YYYY
+  - Packaging changes
+
+    - The structure of the ``doc`` directory is different. The PDF
+      documentation is in the same place, but the files for the
+      previous HTML documentation are no longer there. Instead, there
+      are ``html`` and ``singlehtml`` directories, each of which
+      contain ``index.html`` and other files and directories. The
+      distribution files and ``make install`` target handle this, but
+      if you are building your own packages and including
+      documentation, please double check to make sure that you are
+      including the right documentation files.
+
+    - The documentation sources have been switched from docbook to
+      reStructuredText processed with `Sphinx
+      <https://sphinx-doc.org>`__. This will break previous
+      documentation links. A redirect is in place on the main website.
+      A top-to-bottom review of the documentation is planned for an
+      upcoming release.
+
   - Library Enhancements
  
     - Since qpdf version 8, using object accessor methods on an
@@ -58,16 +77,6 @@ For a detailed list of changes, please see the file
  
     - Add ``qpdf_oh_get_type_code`` and ``qpdf_oh_get_type_name``.
  
-  - Documentation change
-
-    - The documentation sources have been switched from docbook to
-      reStructuredText processed with `Sphinx
-      <https://sphinx-doc.org>`__. This is mostly transparent (other
-      than format change) with the exception that all section links
-      have changed. What used to be `#ref.something` is now
-      `#something`. A top-to-bottom review of the documentation is
-      planned for an upcoming release.
-
 10.4.0: November 16, 2021
   - Handling of Weak Cryptography Algorithms
  
@@ -21,6 +21,6 @@ This program should not be used as a general purpose compression
 tool.  Use something like gzip(1) instead.
 .PP
 For details about qpdf, please see the qpdf manual, which can be found
-in @docdir@/qpdf-manual.html or @docdir@/qpdf-manual.pdf.
+in @docdir@/html/index.html or @docdir@/qpdf-manual.pdf.
 .SH "SEE ALSO"
 qpdf(1), gzip(1)