Add offline documentation

Offline documentation is provided in both PDF and HTML form.
As the extension used to build the PDF may come with dependency issues,
it is commented out in `requirements.txt`. Both offline versions will be
created manually as part of the release process by a technical writer
and added to GitHub.

Change to the glossary page fixes an issue with linking
within the PDF.the TOC on the title page shows 2 levels, which makes the
PDF simpler to navigate.

QA: Checked that "Offline Version" link in footer would link to
`/releases/` if dev version of docs, otherwise to the release version.
Checked rendered output in browser. Ran linkcheck.

This commit addresses FFTK-1785

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

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

@@ -10,3 +10,5 @@ sphinx-prompt==1.5.0
 sphinx-reredirects
 sphinx-autobuild
 meilisearch
+# uncomment when building PDF. May require additional system dependencies.
+# sphinx-simplepdf

source/_templates/footer.html

@@ -0,0 +1,10 @@
+{% extends "!footer.html" %}
+{%-block contentinfo %}
+{{ super }}
+
+<div class="download" data-toggle="link" role="note" aria-label="Link">
+  <a href="https://github.com/foundriesio/docs/{{ gh_release }}/" target="_blank" rel="noreferrer noopener" Link>
+   <button type="button" button style="margin:10px;"> Offline Version </button>
+   </a>
+</div>
+{% endblock %}

source/conf.py

@@ -94,10 +94,18 @@
         else:
             search_version = 'default'
 
-# pass to template engine's context
+# Used for link in footer to the GitHub releases page.
+
+if mp_version.startswith('git-'):
+    gh_release = 'releases'
+else:
+    gh_release = 'releases/tag/mp-' + mp_version
+
+# pass vars to template engine's context
 html_context = {'search_version': search_version,
                 'meilisearch_host': meilisearch_host,
                 'meilisearch_search_key': meilisearch_search_key,
+                'gh_release': gh_release,
 }
 
 # -- General configuration ------------------------------------------------
@@ -114,7 +122,7 @@
 # a repository and checking out master, but it works for subscriber
 # updates.)
 if mp_version.startswith('git-'):
-    git_tag = 'master'
+    git_tag = 'main'
 else:
     git_tag = 'mp-' + mp_version + mp_tags
 
@@ -187,6 +195,16 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+simplepdf_vars = {
+        'primary': '#2C1256',
+        'secondary': '#000000',
+        'cover': '#2C1256',
+        'cover-bg': 'white',
+        'links': '#2980B9',
+        }
+
+simplepdf_file_name = 'FoundriesFactory_' + mp_version + '.pdf'
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']

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: 2
    :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: 2
    :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: 2
    :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: 2
    :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: 2
    :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