From 2cacd1f364f54de1252e223501725a77a3d72df7 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Thu, 18 Jul 2024 15:33:36 +1200
Subject: [PATCH] Semi complete discussion on PR preview limits

Aimed at an internal audience, but hits most of the main points and will need to be updated before merging upstream.
---
 docs/source/appendix.rst               |  1 +
 docs/source/appendix/building_docs.rst | 34 ++++++++++++++++++++++++++
 docs/source/conf.py                    |  2 +-
 3 files changed, 36 insertions(+), 1 deletion(-)
 create mode 100644 docs/source/appendix/building_docs.rst

diff --git a/docs/source/appendix.rst b/docs/source/appendix.rst
index 0b0a2d15b5d..97eb4568f90 100644
--- a/docs/source/appendix.rst
+++ b/docs/source/appendix.rst
@@ -5,6 +5,7 @@ Appendix
 	:maxdepth: 2
 	:includehidden:
 
+	appendix/building_docs
 	appendix/primer
 	appendix/auxlibs
 	appendix/auxprogs
diff --git a/docs/source/appendix/building_docs.rst b/docs/source/appendix/building_docs.rst
new file mode 100644
index 00000000000..a48959037ea
--- /dev/null
+++ b/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
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 7c8ae21cb7b..984c4dab5ec 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -62,7 +62,7 @@
         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"] = "<strong>Oh no!</strong> This looks like a ReadTheDocs build, possibly for a PR preview, that's missing some generated content!"
+        html_theme_options["announcement"] = 'Missing content? Check <a class="reference internal" href="https://tyrtd--2.org.readthedocs.build/en/2/appendix/building_docs.html#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)"