From 426b4ce8565e4f9143c122fd3afbcc22598fc6c4 Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Sat, 18 Dec 2021 11:19:20 -0500 Subject: Update documentation build/installation --- manual/build.mk | 31 +++++++++---------------------- manual/fix-qdf.1.in | 2 +- manual/installation.rst | 2 +- manual/qpdf.1.in | 2 +- manual/release-notes.rst | 29 +++++++++++++++++++---------- manual/zlib-flate.1.in | 2 +- 6 files changed, 32 insertions(+), 36 deletions(-) (limited to 'manual') diff --git a/manual/build.mk b/manual/build.mk index 6d38bc3a..b07bf830 100644 --- a/manual/build.mk +++ b/manual/build.mk @@ -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 diff --git a/manual/fix-qdf.1.in b/manual/fix-qdf.1.in index b14f4304..dbc4c106 100644 --- a/manual/fix-qdf.1.in +++ b/manual/fix-qdf.1.in @@ -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. diff --git a/manual/installation.rst b/manual/installation.rst index 8862034d..d7989e66 100644 --- a/manual/installation.rst +++ b/manual/installation.rst @@ -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 `__. 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. diff --git a/manual/qpdf.1.in b/manual/qpdf.1.in index 18c6f704..7d8112dd 100644 --- a/manual/qpdf.1.in +++ b/manual/qpdf.1.in @@ -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. diff --git a/manual/release-notes.rst b/manual/release-notes.rst index 5a8fd307..adb2a48d 100644 --- a/manual/release-notes.rst +++ b/manual/release-notes.rst @@ -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 + `__. 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 - `__. 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 diff --git a/manual/zlib-flate.1.in b/manual/zlib-flate.1.in index e74eb3f5..77349c36 100644 --- a/manual/zlib-flate.1.in +++ b/manual/zlib-flate.1.in @@ -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) -- cgit v1.2.3-54-g00ecf