Add offline documentation via pdf

Added basic configuration and support for generating PDF version of the
documentation. This is done with simplepdf.

Also added to the jobserv.yml file for PR requests, which will need to be
tested.

QA steps: built PDF and HTML. Checked that HTML would build with missing
PDF. Checked that PDf download worked from both top index page and any
other page. Checked that PDF links worked and output was readable.
Note that simplepdf will report errors due to links in sidebar.These can
be ignored.

This commit addresses task FFTK-1795
This commit applies to FFPK-93
This commit applies to FS-1826

Signed-off-by: Katrina Prosise <[email protected]>

.jobserv.yml

@@ -16,7 +16,8 @@ triggers:
 scripts:
   make-docs: |
     #!/bin/sh -ex
-    apk add --update make git graphviz curl ttf-freefont gcc musl-dev python3-dev
+    apk add --update make git graphviz curl ttf-freefont gcc g++ musl-dev python3-dev weasyprint
+    pip install --upgrade wheel
     pip install -r ./requirements.txt
 
     echo == $(date "+%F %T") Setting up fioctl docs
@@ -25,7 +26,7 @@ scripts:
     chmod +x /tmp/fioctl
     /tmp/fioctl gen-rst ./source/reference-manual/factory/fioctl/
 
-    make OUTDIR=/archive SPHINXBUILD=sphinx-build singlehtml html
+    make OUTDIR=/archive SPHINXBUILD=sphinx-build simplepdf singlehtml html
 
     urlbase="https://ci.foundries.io/projects/${H_PROJECT}/builds/${H_BUILD}/${H_RUN}/"
 

Makefile

@@ -34,6 +34,12 @@ html:
 	@echo
 	@echo "Build finished. The HTML pages are in $(OUTDIR)/html."
 
+.PHONY: simplepdf
+simplepdf:
+	$(SPHINXBUILD) -M simplepdf source $(OUTDIR)/pdf
+	@echo
+	@echo "Build finished. The PDF is in $(OUTDIR)/pdf."
+
 .PHONY: dirhtml
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(OUTDIR)/dirhtml

requirements.txt

@@ -1,4 +1,4 @@
-setuptools==69.2.0
+setuptools==70.0.0
 sphinx-rtd-theme==1.3.0
 sphinx==5.3.0
 sphinxcontrib-contentui==0.2.5
@@ -10,3 +10,4 @@ sphinx-prompt==1.5.0
 sphinx-reredirects
 sphinx-autobuild
 meilisearch
+sphinx-simplepdf

source/_templates/footer.html

@@ -0,0 +1,10 @@
+{% extends "!footer.html" %}
+{%-block contentinfo %}
+{{ super }}
+
+<div class="download" data-toggle="download" role="note" aria-label="Download">
+   <a href="{{ pathto(download,1) }}" Download>
+   <button type="button" button style="margin:10px;"> Offline Version </button>
+   </a>
+</div>
+{% endblock %}

source/conf.py

@@ -152,6 +152,16 @@
 
 sphinx_tabs_valid_builders = ['linkcheck']
 
+simplepdf_vars = {
+        'primary': '#2C1256',
+        'secondary': '#000000',
+        'cover': '#2C1256',
+        'cover-bg': 'white',
+        'links': '#2980B9',
+        }
+
+simplepdf_file_name = 'FoundriesFactory_' + mp_version + '.pdf'
+
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
@@ -197,6 +207,10 @@
 # The master toctree document.
 master_doc = 'index'
 
+# PDF location of docs, used by _templates/footer.html
+# html_context['download'] =  '_static/downloads/docs.pdf'
+html_context['download'] =  '../pdf/simplepdf/' + simplepdf_file_name
+
 # General information about the project.
 project = 'FoundriesFactory'
 copyright = '2017-2024, Foundries.io, Ltd'
@@ -328,7 +342,7 @@
 
 # Custom sidebar templates, maps document names to template names.
 html_sidebars = {
-        '**': ['searchbox.html']
+        '**': ['searchbox.html'],
         }
 
 # Additional templates that should be rendered to pages, maps page names to

source/glossary/index.rst

@@ -1,5 +1,7 @@
-Terminology
-===========
+.. _glossary:
+
+Glossary
+========
 
 .. Glossary::
    :sorted:

source/index.rst

@@ -7,7 +7,7 @@ customize open source software projects including U-Boot, OP-TEE,
 OE/Yocto Project, the Linux microPlatform™ and Docker®.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 3
    :caption: Getting started
    :name: sec-learn
 
@@ -19,7 +19,7 @@ OE/Yocto Project, the Linux microPlatform™ and Docker®.
    getting-started/building-deploying-app/index
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 3
    :caption: Tutorials
    :name: sec-tutorials
 
@@ -32,7 +32,7 @@ OE/Yocto Project, the Linux microPlatform™ and Docker®.
    tutorials/working-with-tags/working-with-tags
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 3
    :glob:
    :caption: User Guide
    :name: sec-user-guide
@@ -53,7 +53,6 @@ OE/Yocto Project, the Linux microPlatform™ and Docker®.
    user-guide/lmp-device-auto-register/lmp-device-auto-register
    user-guide/custom-sota-client
    user-guide/offline-update/offline-update
-   porting-guide/pg
    reference-manual/linux/linux-disk-encryption
    reference-manual/linux/factory-device-reset
    reference-manual/linux/linux-update
@@ -68,7 +67,7 @@ OE/Yocto Project, the Linux microPlatform™ and Docker®.
    user-guide/troubleshooting/troubleshooting
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 3
    :caption: Reference Manual
    :name: sec-manual
 
@@ -83,21 +82,19 @@ OE/Yocto Project, the Linux microPlatform™ and Docker®.
    reference-manual/testing/testing
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 3
    :caption: Porting Guide
    :name: sec-porting-guide
 
    porting-guide/pg.rst
 
 .. toctree::
-   :maxdepth: 2
    :caption: Glossary
    :name: sec-glossary
 
    glossary/index
 
 .. toctree::
-   :maxdepth: 2
    :caption: Release Notes
    :name: sec-release-notes