Testing PRs

docs/source/appendix.rst

@@ -5,6 +5,7 @@ Appendix
 	:maxdepth: 2
 	:includehidden:
 
+	appendix/building_docs
 	appendix/primer
 	appendix/auxlibs
 	appendix/auxprogs

docs/source/appendix/building_docs.rst

@@ -0,0 +1,34 @@
+Building the documentation
+==========================
+
+A portion of the documentation is generated dynamically by using Yosys during
+the build process.
+
+More stuff here.
+
+PR previews and limitations
+---------------------------
+
+Because we are building from the Yosys repo, we can preview PRs (like this
+one!).
+
+As described above, some of the content in the documentation is generated
+dynamically.  While this has the benefit of always staying up-to-date with the
+latest version of Yosys (including any local changes you might make), it does
+mean that some parts of the documentation will be missing when using the Read
+the Docs PR preview feature.  This includes most images that are generated from
+:cmd:ref:`show`, some other images that are built from ``.tex`` source, as well
+as all of the :doc:`/cmd_ref` and the upcoming cell reference.
+
+`YosysHQ/Yosys#4376`_ adds a step to the test docs action which not only
+attempts to build the docs with the Yosys build being tested, but it will also
+then upload artifacts for both the pdf and html builds.  If the PR being
+(p)reviewed changes this generated content then it is possible to download these
+artifacts to check the Sphinx output (see: the corresponding `action run`_ from
+the PR referenced, although the artifacts for it are expired and no longer
+available).  Note that the current version in that PR only builds Yosys without
+Verific, if documentation changes for Yosys+Verific are expected then it would
+be reasonably straight-forward to update `test-verific.yml` instead.
+
+.. _YosysHQ/Yosys#4376: https://github.com/YosysHQ/yosys/pull/4376
+.. _action run: https://github.com/YosysHQ/yosys/actions/runs/9246974933

docs/source/conf.py

@@ -41,20 +41,30 @@
 pygments_style = 'colorful'
 highlight_language = 'none'
 
-extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.bibtex', 'rtds_action']
-
-# The name of your GitHub repository
-rtds_action_github_repo = "KrystalDelusion/yosys"
-
-# The path where the artifact should be extracted
-# Note: this is relative to the conf.py file!
-rtds_action_path = "."
-
-# The "prefix" used in the `upload-artifact` step of the action
-rtds_action_artifact_prefix = "cmd-ref-"
-
-# A GitHub personal access token is required, more info below
-rtds_action_github_token = os.environ["GITHUB_TOKEN"]
+extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.bibtex']
+
+if os.getenv("READTHEDOCS"):
+    # Use rtds_action if we are building on read the docs and have a github token env var
+    if os.getenv("GITHUB_TOKEN"):
+        extensions += ['rtds_action']
+
+        # The name of your GitHub repository
+        rtds_action_github_repo = "KrystalDelusion/yosys"
+
+        # The path where the artifact should be extracted
+        # Note: this is relative to the conf.py file!
+        rtds_action_path = "."
+
+        # The "prefix" used in the `upload-artifact` step of the action
+        rtds_action_artifact_prefix = "cmd-ref-"
+
+        # A GitHub personal access token is required for full RTD builds
+        rtds_action_github_token = os.environ["GITHUB_TOKEN"]
+    else:
+        # We're on read the docs but have no github token, this is probably a PR preview build
+        html_theme_options["announcement"] = 'Missing content? Check <a class="reference internal" href="https://tyrtd--2.org.readthedocs.build/en/2/appendix/building_docs.html#pr-previews-and-limitations">PR preview limitations</a>.'
+        html_theme_options["light_css_variables"]["color-announcement-background"] = "var(--color-admonition-title-background--caution)"
+        html_theme_options["light_css_variables"]["color-announcement-text"] = "var(--color-content-foreground)"
 
 # Ensure that autosectionlabel will produce unique names
 autosectionlabel_prefix_document = True