From 1ebde8fd0373ce506a2b6972cb80c7f3f79be29b Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Thu, 18 Jul 2024 12:01:01 +1200
Subject: [PATCH 1/4] conf.py: Gate rtds_action
Also add a proto warning announcement if it looks like a PR preview (since it won't have any generated content).
---
docs/source/conf.py | 38 ++++++++++++++++++++++++--------------
1 file changed, 24 insertions(+), 14 deletions(-)
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 97560adcbcc..6037c81a0b7 100644
--- a/docs/source/conf.py
+++ b/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"] = "Oh no! This looks like a ReadTheDocs build, possibly for a PR preview, that's missing some generated content!"
+ 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
From 1f9b0153e1a5c3693ad957e62e6a9eedb39fd3a7 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Thu, 18 Jul 2024 12:04:00 +1200
Subject: [PATCH 2/4] Fix conf.py formatting
---
docs/source/conf.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 6037c81a0b7..7c8ae21cb7b 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -45,7 +45,7 @@
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"]:
+ if os.getenv("GITHUB_TOKEN"):
extensions += ['rtds_action']
# The name of your GitHub repository
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 3/4] 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"] = "Oh no! This looks like a ReadTheDocs build, possibly for a PR preview, that's missing some generated content!"
+ html_theme_options["announcement"] = 'Missing content? Check PR preview limitations.'
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)"
From a31be5a8a70fbb12c3edb1bae7fbcad439afcdfd Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Thu, 18 Jul 2024 15:35:33 +1200
Subject: [PATCH 4/4] Fix link
---
docs/source/conf.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 984c4dab5ec..d3f946e7478 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"] = 'Missing content? Check PR preview limitations.'
+ html_theme_options["announcement"] = 'Missing content? Check PR preview limitations.'
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)"