foundriesio · kprosise · Jan 2, 2025 · Dec 26, 2024
diff --git a/.jobserv.yml b/.jobserv.yml
@@ -4,12 +4,12 @@ triggers:
     type: github_pr
     runs:
       - name: docs
-        container: python:3.9-alpine
+        container: python:3.12-alpine
         host-tag: fio-internal-ci
         script: make-docs
 
       - name: link-check
-        container: python:3.9-alpine
+        container: python:3.12-alpine
         host-tag: fio-internal-ci
         script: link-check
 

diff --git a/README.md b/README.md
@@ -12,15 +12,15 @@
 
 Before beginning any work, review the [contributing section](#contributing).
 
-To build the documentation, python3 and `pip3` are required.
+To build the documentation, python3 (3.11 or greater) and `pip3` are required.
 All required python modules are listed in `requirements.txt`.
-Install them with `pip3 install -r requirements.txt`.
+Install them with `pip3 install -r requirements.txt`. _virtual environment recommended_
 
 📌 **NOTE:** After run `pip3 install -r requirements.txt`, restart your terminal or use source to ensure Sphinx is set up.
 
-### Using Virtualenv to Provide Requirements
+### Using a Virtual Environment to Provide Requirements
 
-To avoid messing with your system-wide package storage, use `virtualenv`.
+To avoid messing with your system-wide package storage, use `virtualenv`, or the builtin `venv`.
 This will set up the necessary environment for sphinx packages and place them here:
 
 ```bash
@@ -32,6 +32,8 @@
 
 ```
 
+**NOTE:** You may need to specify the python version when initializing the virtual environment.
+
 ## Building the Docs Locally
 
 To build the html from rst files, from the top directory run:

diff --git a/requirements.txt b/requirements.txt
@@ -1,14 +1,14 @@
 setuptools==70.0.0
-sphinx-rtd-theme==1.3.0
-sphinx==5.3.0
-sphinxcontrib-contentui==0.2.5
-sphinx-tabs==3.4.1
-sphinxemoji==0.2.0
-sphinx_copybutton==0.5.2
-sphinx_toolbox==3.5.0
-sphinx-prompt==1.5.0
+sphinx-rtd-theme==3.0.2
+sphinx==8.1.3
+sphinxcontrib-contentui>=0.2.5
+sphinx-tabs
+sphinxemoji>=0.2.0
+sphinx_copybutton>=0.5.2
+sphinx_toolbox
+sphinx-prompt>=1.5.0
 sphinx-reredirects
 sphinx-autobuild
 meilisearch
 # uncomment when building PDF. May require additional system dependencies.
-# sphinx-simplepdf
+#sphinx-simplepdf
diff --git a/source/_templates/footer.html b/source/_templates/footer.html
@@ -1,6 +1,5 @@
 {% 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>
@@ -11,5 +10,6 @@
 <div class="has-text-centered is-size-7 mb-2 px-6 mx-6">
   <p>Linux<sup>&reg;</sup> is the registered trademark of Linus Torvalds in the U.S. and other countries.</p>
 </div>
+{{ super() }}
 
 {% endblock %}
diff --git a/source/_templates/layout.html b/source/_templates/layout.html
@@ -19,7 +19,7 @@
 {% block sidebartitle %}
 
 <a href="https://cta-eu1.hubspot.com/web-interactives/public/v1/track/redirect?encryptedPayload=AVxigLJoSaECsY7AgSp8%2B%2FzAJj9MjRdktrFWem7ZiLYUuwu9Ps5ktV52C%2Fp4Nxue86Go1wQ8PAPPjmbHy5hgIFaiHKCuH8%2BKOg1V2VD010z%2BH2jGMmM%3D&webInteractiveContentId=113594058467&portalId=26493592" target="_blank" rel="noopener" crossorigin="anonymous">
-  <img src="{{ pathto('_static/' + logo, 1) }}" class="logo"/>
+  <img src="{{ logo_url }}" class="logo"/>
 </a>
 
 <div class="version">

diff --git a/source/conf.py b/source/conf.py
@@ -158,12 +158,14 @@
 
 copybutton_prompt_text = "$ "
 
-sphinx_tabs_valid_builders = ['linkcheck']
-linkcheck_retries = 3
-linkcheck_anchors_ignore = ['L189-L192']
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
+# Linkcheck config
+sphinx_tabs_valid_builders = ['linkcheck']
+linkcheck_retries = 3
+linkcheck_anchors_ignore = ['L189-L192']
+linkcheck_allow_unauthorized = True
 # Links that shouldn't get checked for validity
 linkcheck_ignore = [
     r'http://localhost:\d+/?',
@@ -172,7 +174,6 @@
     'http://.*[.]local',
     'http://your-device-ip-address/',
     'https://app.atsgarage.com/#/.*',        # requires login
-    # This site is causing false negatives:
     r'https://elinux.org/.*',
     r'https://blogs.msdn.microsoft.com/.*',  # temporary blacklist
     r'https://www.tcpdump.org/.*',           # ditto
@@ -188,8 +189,11 @@
     r'https://wiki.st.com/.*',
     'https://ngrok.com', # ssl cert expired, will likely want to remove from docs if this persists
     'https://www.nxp.com/docs/en/application-note/AN12312.pdf',
+    r'https://sourceforge.net/.*', # 403 error
+    'https://www.nsa.gov/portals/75/documents/what-we-do/cybersecurity/professional-resources/csi-uefi-lockdown.pdf', # 403 error
+    'https://www.xilinx.com/products/silicon-devices/acap/versal',
+    r'https://source.foundries.io/factories/.*',
 ]
-
 # Time in seconds to wait for a response. May result in false errors, but also keeps things from timing out
 linkcheck_timeout = 10
 
@@ -219,7 +223,7 @@
 
 # General information about the project.
 project = 'FoundriesFactory'
-copyright = '2017-2024, Foundries.io, Ltd'
+copyright = '2017-%Y, Foundries.io, Ltd'
 author = 'Foundries.io, Ltd.'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -298,9 +302,9 @@
 
 # Note that for Sphinx-RTD v0.6.0 or newer, 'html_baseurl' is used rather
 # than canonical_url
+#html_baseurl = 'https://docs.foundries.io/latest/',
 html_theme_options = {
     'logo_only': False,
-    'canonical_url': 'https://docs.foundries.io/latest/',
     'collapse_navigation': False,
     'sticky_navigation': False,
     'navigation_depth': -1,
@@ -322,7 +326,6 @@
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 html_logo = "_static/logo.png"
-
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
@@ -376,7 +379,7 @@
 #html_show_sphinx = True
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
+html_show_copyright = True
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
@@ -404,7 +407,7 @@
 htmlhelp_basename = 'fiodoc'
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+#intersphinx_mapping = {'https://docs.python.org/': None}
 
 # Config for sphinx-reredirects, maps source: target, target path is relative to source.
 # TODO: troubleshooting sections redirecting to lmp-customization do not appear to be functional

diff --git a/source/reference-manual/factory/api-access.rst b/source/reference-manual/factory/api-access.rst
@@ -101,13 +101,13 @@ Targets
    https://app.foundries.io/settings/credentials
 
 .. _REST APIs:
-   https://api.foundries.io/ota/
+   https://api.foundries.io/ota
 
 .. _Git repositories:
-   https://source.foundries.io/
+   https://source.foundries.io
 
 .. _Factory containers:
-   https://hub.foundries.io/
+   https://hub.foundries.io
 
 .. _OAuth2:
-   https://oauth.net/2/
+   https://oauth.net/2
diff --git a/source/reference-manual/linux/linux-update.rst b/source/reference-manual/linux/linux-update.rst
@@ -20,7 +20,7 @@ It also shows common update problems and how to solve them.
     Similar steps are taken for different reference hardware and LmP versions.
 
 .. important:: 
-    See :ref:`release notes <changelog>` for things to be aware of when updating to a given release.
+    See release notes under the table of content for things to be aware of when updating to a given release.
 
 .. tip::
     When facing issues to reproduce these steps, do not hesitate to contact `Foundries.io support <https://support.foundries.io/>`_.

diff --git a/source/reference-manual/security/secure-boot-uefi.rst b/source/reference-manual/security/secure-boot-uefi.rst
@@ -335,7 +335,7 @@ Additional Documentation and References
 ---------------------------------------
 
 * `Managing EFI Boot Loaders for Linux: Controlling Secure Boot <https://www.rodsbooks.com/efi-bootloaders/controlling-sb.html>`_
-* `Understanding UEFI Secure Boot Chain <https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain/>`_
+* `Understanding UEFI Secure Boot Chain <https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain>`_
 * `NSA UEFI Lockdown Quick Guidance <https://www.nsa.gov/portals/75/documents/what-we-do/cybersecurity/professional-resources/csi-uefi-lockdown.pdf>`_
 * `NSA UEFI Secure Boot Customization <https://media.defense.gov/2020/Sep/15/2002497594/-1/-1/0/CTR-UEFI-Secure-Boot-Customization-UOO168873-20.PDF>`_
 

diff --git a/source/user-guide/foundriesio-rest-api/foundriesio-rest-api.rst b/source/user-guide/foundriesio-rest-api/foundriesio-rest-api.rst
@@ -264,7 +264,7 @@
 Learning More About the REST API
 --------------------------------
 
-Logged into http://app.foundries.io, you may interact with the REST API from your browser at http://api.foundries.io/ota. 
+Logged into http://app.foundries.io, you may interact with the `REST API from your browser at <http://api.foundries.io/ota>`. 
 
 1. Click on the operation to test.
    This shows the :guilabel:`Try it out` option.