From 2e1335a0233abcfc833df2b5f6169f817ed12c40 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Fri, 23 Aug 2024 10:06:32 +1200
Subject: [PATCH 01/17] Docs: Fix local builds

Based on the docs-test-fork PR branch, includes PR preview announcement, linking to the relevant tyrtd page
---
 docs/source/conf.py | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 23efe2b43c2..4719dc89e6a 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -41,13 +41,21 @@
 pygments_style = 'colorful'
 highlight_language = 'none'
 
-extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.bibtex', 'rtds_action']
-
-# rtds_action
-rtds_action_github_repo = "YosysHQ/yosys"
-rtds_action_path = "."
-rtds_action_artifact_prefix = "cmd-ref-"
-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']
+        rtds_action_github_repo = "YosysHQ/yosys"
+        rtds_action_path = "."
+        rtds_action_artifact_prefix = "cmd-ref-"
+        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

From 0b53b10770f747926ecedd46a68571eb6ef1ee73 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Fri, 23 Aug 2024 12:36:41 +1200
Subject: [PATCH 02/17] Makefile: Stop unconditionally install docs prereqs

---
 Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 0888ae3b53c..1967f0c639c 100644
--- a/Makefile
+++ b/Makefile
@@ -1010,7 +1010,7 @@ docs/reqs:
 	$(Q) $(MAKE) -C docs reqs
 
 DOC_TARGET ?= html
-docs: docs/source/cmd/abc.rst docs/gen_examples docs/gen_images docs/guidelines docs/usage docs/reqs
+docs: docs/source/cmd/abc.rst docs/gen_examples docs/gen_images docs/guidelines docs/usage
 	$(Q) $(MAKE) -C docs $(DOC_TARGET)
 
 clean:

From 5d5d890d5b8283ac42c7f912d3c23f5a70387b2c Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Fri, 23 Aug 2024 12:52:15 +1200
Subject: [PATCH 03/17] Docs: macos-safe build

Swap `cp -u` for `rsync -t`.
Drop the workaround to get the list of dot files after copying them, and instead just run the makefile twice.
Swap `$(wildcard **/*.x)` for `$(shell find . -name *.x)`,
---
 docs/Makefile                |  1 +
 docs/source/_images/Makefile | 16 +++++++---------
 2 files changed, 8 insertions(+), 9 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 701157ee6c3..8be970391a3 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -250,6 +250,7 @@ test-macros:
 .PHONY: images
 images:
 	$(MAKE) -C source/_images
+	$(MAKE) -C source/_images convert
 
 .PHONY: reqs
 reqs:
diff --git a/docs/source/_images/Makefile b/docs/source/_images/Makefile
index 955805f9c58..26cc47284c3 100644
--- a/docs/source/_images/Makefile
+++ b/docs/source/_images/Makefile
@@ -8,24 +8,22 @@ FAKETIME := TZ='Z' faketime -f '2022-01-01 00:00:00 x0,001'
 CODE_EXAMPLES := ../code_examples/*/Makefile
 examples: $(CODE_EXAMPLES)
 
-# target to convert specified dot file(s)
+# target to convert all dot files
+# needs to be run *after* examples, otherwise no dot files will be found
 .PHONY: convert
-TARG_DOT ?=
-convert: $(TARG_DOT:.dot=.pdf) $(TARG_DOT:.dot=.svg)
+DOT_FILES := $(shell find . -name *.dot)
+convert: $(DOT_FILES:.dot=.pdf) $(DOT_FILES:.dot=.svg)
 
-# use empty FORCE target because .PHONY ignores % expansion, using find allows
-# us to generate everything in one pass, since we don't know all of the possible
-# outputs until the sub-makes run
+# use empty FORCE target because .PHONY ignores % expansion
 FORCE:
 ../%/Makefile: FORCE
 	@make -C $(@D) dots
 	@mkdir -p $*
-	@find $(@D) -name *.dot -exec cp -u {} -t $* \;
-	@find $* -name *.dot -printf "%p " | xargs -i make --no-print-directory convert TARG_DOT="{}"
+	@find $(@D) -name *.dot -exec rsync -t {} $* \;
 
 # find and build all tex files
 .PHONY: all_tex
-TEX_FILES := $(wildcard **/*.tex)
+TEX_FILES := $(shell find . -name *.tex)
 all_tex: $(TEX_FILES:.tex=.pdf) $(TEX_FILES:.tex=.svg)
 
 %.pdf: %.dot

From 7d63fdd88eb99e4d6951fd86dab87537eff3bb43 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Fri, 23 Aug 2024 12:53:38 +1200
Subject: [PATCH 04/17] README: building docs on macos

---
 README.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/README.md b/README.md
index 7437bb2832b..c806ec28340 100644
--- a/README.md
+++ b/README.md
@@ -629,6 +629,10 @@ following are used for building the website:
 
 	$ sudo apt install pdf2svg faketime
 
+Or for MacOS, using homebrew:
+
+  $ brew install pdf2svg libfaketime
+
 PDFLaTeX, included with most LaTeX distributions, is also needed during the
 build process for the website.  Or, run the following:
 

From 98d26bdd2c054d31cb17785e3192ccaa944972f9 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Mon, 26 Aug 2024 10:55:01 +1200
Subject: [PATCH 05/17] Docs: Fix nested list on build_verific page

---
 .../yosys_internals/extending_yosys/build_verific.rst       | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/source/yosys_internals/extending_yosys/build_verific.rst b/docs/source/yosys_internals/extending_yosys/build_verific.rst
index b20517bd3dd..2585ebae4b3 100644
--- a/docs/source/yosys_internals/extending_yosys/build_verific.rst
+++ b/docs/source/yosys_internals/extending_yosys/build_verific.rst
@@ -81,8 +81,10 @@ The following features, along with their corresponding Yosys build parameters,
 are required for the Yosys-Verific patch:
 
 * RTL elaboration with
-   * SystemVerilog with ``ENABLE_VERIFIC_SYSTEMVERILOG``, and/or
-   * VHDL support with ``ENABLE_VERIFIC_VHDL``.
+
+  * SystemVerilog with ``ENABLE_VERIFIC_SYSTEMVERILOG``, and/or
+  * VHDL support with ``ENABLE_VERIFIC_VHDL``.
+
 * Hierarchy tree support and static elaboration with
   ``ENABLE_VERIFIC_HIER_TREE``.
 

From 83692075df13430e641c8e263c0615136dd3857e Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Tue, 27 Aug 2024 09:50:29 +1200
Subject: [PATCH 06/17] ci: Don't cancel previous builds

Which is what the comment said, but the code didn't match.
---
 .github/workflows/test-verific.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/test-verific.yml b/.github/workflows/test-verific.yml
index 627a70d4794..07c2aa4d181 100644
--- a/.github/workflows/test-verific.yml
+++ b/.github/workflows/test-verific.yml
@@ -13,7 +13,7 @@ jobs:
         with:
           paths_ignore: '["**/README.md"]'
           # don't cancel previous builds
-          cancel_others: 'true'
+          cancel_others: 'false'
           # only run on push *or* pull_request, not both
           concurrent_skipping: 'same_content_newer'
           # we have special actions when running on main, so this should be off

From a20756676cc9dc56bdd42686525736f8145dcb84 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Tue, 27 Aug 2024 09:56:07 +1200
Subject: [PATCH 07/17] ci: Update RTDs trigger conditional

Trigger on main, on a branch called `docs-preview*`, or on any tag.
---
 .github/workflows/test-verific.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/test-verific.yml b/.github/workflows/test-verific.yml
index 07c2aa4d181..18172324257 100644
--- a/.github/workflows/test-verific.yml
+++ b/.github/workflows/test-verific.yml
@@ -112,7 +112,7 @@ jobs:
             docs/source/code_examples
 
       - name: Trigger RTDs build
-        if: ${{ github.ref == 'refs/heads/main' }}
+        if: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/docs-preview') || startsWith(github.ref, 'refs/tags/') }}
         uses: dfm/rtds-action@v1.1.0
         with:
           webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }}

From ecff434886f685b1dce0637ed7af62a342d0d304 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Tue, 27 Aug 2024 10:21:31 +1200
Subject: [PATCH 08/17] Docs: Use version name from readthedocs

Latest still gets -dev, but if it's a docs preview use the tag/branch name.
---
 docs/source/conf.py | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 4719dc89e6a..2dc370c4b4d 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -62,8 +62,12 @@
 autosectionlabel_maxdepth = 1
 
 # set version
-if os.getenv("READTHEDOCS") and os.getenv("READTHEDOCS_VERSION") == "latest":
-    release = yosys_ver + "-dev"
+if os.getenv("READTHEDOCS"):
+    rtds_version = os.getenv("READTHEDOCS_VERSION")
+    if rtds_version == "latest":
+        release = yosys_ver + "-dev"
+    else:
+        release = rtds_version
 else:
     release = yosys_ver
 

From 840c515ffc61cf6c8f5b79f9435c8fabbc8f7c75 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Tue, 3 Sep 2024 10:20:24 +1200
Subject: [PATCH 09/17] RTDs: Fail on warning

Fix outstanding sphinx warnings;
- Change mycells.lib to use `text` parsing instead of (currently) unsupported `Liberty`.
- Remove unused `troubleshooting.rst`, moving the todo into the index.
---
 .readthedocs.yaml                                          | 1 +
 docs/source/using_yosys/more_scripting/index.rst           | 2 ++
 docs/source/using_yosys/more_scripting/troubleshooting.rst | 6 ------
 docs/source/using_yosys/synthesis/cell_libs.rst            | 4 +++-
 4 files changed, 6 insertions(+), 7 deletions(-)
 delete mode 100644 docs/source/using_yosys/more_scripting/troubleshooting.rst

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index cb700dc1c72..4a04219de98 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -13,6 +13,7 @@ formats:
 
 sphinx:
   configuration: docs/source/conf.py
+  fail_on_warning: true
 
 python:
   install:
diff --git a/docs/source/using_yosys/more_scripting/index.rst b/docs/source/using_yosys/more_scripting/index.rst
index 490a5a7ad8b..090b9e0b950 100644
--- a/docs/source/using_yosys/more_scripting/index.rst
+++ b/docs/source/using_yosys/more_scripting/index.rst
@@ -3,6 +3,8 @@ More scripting
 
 .. todo:: brief overview for the more scripting index
 
+.. todo:: troubleshooting document(?)
+
 .. toctree::
    :maxdepth: 3
 
diff --git a/docs/source/using_yosys/more_scripting/troubleshooting.rst b/docs/source/using_yosys/more_scripting/troubleshooting.rst
deleted file mode 100644
index a17a552d2e4..00000000000
--- a/docs/source/using_yosys/more_scripting/troubleshooting.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-Troubleshooting
-~~~~~~~~~~~~~~~
-
-.. todo:: troubleshooting document(?)
-
-See :doc:`/cmd/bugpoint`
diff --git a/docs/source/using_yosys/synthesis/cell_libs.rst b/docs/source/using_yosys/synthesis/cell_libs.rst
index 92b6dab3f58..4e800bdf2b6 100644
--- a/docs/source/using_yosys/synthesis/cell_libs.rst
+++ b/docs/source/using_yosys/synthesis/cell_libs.rst
@@ -90,8 +90,10 @@ Mapping to hardware
 For this example, we are using a Liberty file to describe a cell library which
 our internal cell library will be mapped to:
 
+.. todo:: find a Liberty pygments style?
+
 .. literalinclude:: /code_examples/intro/mycells.lib
-   :language: Liberty
+   :language: text
    :linenos:
    :name: mycells-lib
    :caption: :file:`mycells.lib`

From a97d99cbac73d52b71aeea655790fd5877617e97 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Tue, 3 Sep 2024 11:00:28 +1200
Subject: [PATCH 10/17] ci: Verific skipping conditional on github.ref

Docs jobs should not skip on concurrent jobs (in case a non-docs job is already
running, such as when a commit has been tagged for docs-preview). However, a
successful `test-verific` can allow for a future docs job to skip testing and go
straight to the preview.
---
 .github/workflows/test-verific.yml | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/test-verific.yml b/.github/workflows/test-verific.yml
index 18172324257..c7190fd183a 100644
--- a/.github/workflows/test-verific.yml
+++ b/.github/workflows/test-verific.yml
@@ -1,6 +1,10 @@
 name: Build and run tests with Verific (Linux)
 
 on: [push, pull_request]
+# docs builds are needed for anything on main, any tagged versions, and any tag
+# or branch starting with docs-preview
+env:
+  is_docs_job: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/docs-preview') || startsWith(github.ref, 'refs/tags/') }}
 
 jobs:
   pre-job:
@@ -16,8 +20,8 @@ jobs:
           cancel_others: 'false'
           # only run on push *or* pull_request, not both
           concurrent_skipping: 'same_content_newer'
-          # we have special actions when running on main, so this should be off
-          skip_after_successful_duplicate: 'false'
+          # we can skip testing if it has already passed
+          skip_after_successful_duplicate: 'true'
 
   test-verific:
     needs: pre-job
@@ -74,7 +78,6 @@ jobs:
   prepare-docs:
     name: Generate docs artifact
     needs: [pre-job, test-verific]
-    if: needs.pre-job.outputs.should_skip != 'true'
     runs-on: [self-hosted, linux, x64, fast]
     steps:
       - name: Checkout Yosys
@@ -82,11 +85,13 @@ jobs:
         with:
           persist-credentials: false
           submodules: true
+
       - name: Runtime environment
         run: |
           echo "procs=$(nproc)" >> $GITHUB_ENV
 
       - name: Build Yosys
+        if: ${{ (needs.pre-job.outputs.should_skip != 'true') || env.is_docs_job }}
         run: |
           make config-clang
           echo "ENABLE_VERIFIC := 1" >> Makefile.conf
@@ -97,11 +102,13 @@ jobs:
           make -j${{ env.procs }} ENABLE_LTO=1
 
       - name: Prepare docs
+        if: ${{ (needs.pre-job.outputs.should_skip != 'true') || env.is_docs_job }}
         shell: bash
         run:
           make docs/source/cmd/abc.rst docs/gen_examples docs/gen_images docs/guidelines docs/usage docs/reqs TARGETS= EXTRA_TARGETS=
 
       - name: Upload artifact
+        if: ${{ (needs.pre-job.outputs.should_skip != 'true') || env.is_docs_job }}
         uses: actions/upload-artifact@v4
         with:
           name: cmd-ref-${{ github.sha }}
@@ -112,7 +119,7 @@ jobs:
             docs/source/code_examples
 
       - name: Trigger RTDs build
-        if: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/docs-preview') || startsWith(github.ref, 'refs/tags/') }}
+        if: ${{ env.is_docs_job }}
         uses: dfm/rtds-action@v1.1.0
         with:
           webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }}

From cab781d958476a1f549084f26965021988167a13 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Thu, 29 Aug 2024 09:58:41 +1200
Subject: [PATCH 11/17] Makefile: Move docs prereqs to separate target

---
 Makefile | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 1967f0c639c..21608126db2 100644
--- a/Makefile
+++ b/Makefile
@@ -1009,8 +1009,11 @@ docs/usage: $(addprefix docs/source/generated/,$(DOCS_USAGE_STDOUT) $(DOCS_USAGE
 docs/reqs:
 	$(Q) $(MAKE) -C docs reqs
 
+.PHONY: docs/prep
+docs/prep: docs/source/cmd/abc.rst docs/gen_examples docs/gen_images docs/guidelines docs/usage
+
 DOC_TARGET ?= html
-docs: docs/source/cmd/abc.rst docs/gen_examples docs/gen_images docs/guidelines docs/usage
+docs: docs/prep
 	$(Q) $(MAKE) -C docs $(DOC_TARGET)
 
 clean:

From 6c833d83b8670694d0216858527e893443b5374a Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Thu, 29 Aug 2024 09:59:20 +1200
Subject: [PATCH 12/17] ci: Use docs/prep target

---
 .github/workflows/test-verific.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/test-verific.yml b/.github/workflows/test-verific.yml
index c7190fd183a..1b38b5f4254 100644
--- a/.github/workflows/test-verific.yml
+++ b/.github/workflows/test-verific.yml
@@ -105,7 +105,7 @@ jobs:
         if: ${{ (needs.pre-job.outputs.should_skip != 'true') || env.is_docs_job }}
         shell: bash
         run:
-          make docs/source/cmd/abc.rst docs/gen_examples docs/gen_images docs/guidelines docs/usage docs/reqs TARGETS= EXTRA_TARGETS=
+          make docs/prep TARGETS= EXTRA_TARGETS=
 
       - name: Upload artifact
         if: ${{ (needs.pre-job.outputs.should_skip != 'true') || env.is_docs_job }}

From e92de01ab30c5402ff633a99c6a696a67785b11f Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Tue, 3 Sep 2024 11:40:47 +1200
Subject: [PATCH 13/17] ci: Split out prepare-docs

---
 .github/workflows/prepare-docs.yml | 52 ++++++++++++++++++++++++++++
 .github/workflows/test-verific.yml | 55 ------------------------------
 2 files changed, 52 insertions(+), 55 deletions(-)
 create mode 100644 .github/workflows/prepare-docs.yml

diff --git a/.github/workflows/prepare-docs.yml b/.github/workflows/prepare-docs.yml
new file mode 100644
index 00000000000..9233e6295b4
--- /dev/null
+++ b/.github/workflows/prepare-docs.yml
@@ -0,0 +1,52 @@
+name: Build docs artifact with Verific
+
+on: push
+
+jobs:
+  prepare-docs:
+    # docs builds are needed for anything on main, any tagged versions, and any tag
+    # or branch starting with docs-preview
+    if: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/docs-preview') || startsWith(github.ref, 'refs/tags/') }}
+    runs-on: [self-hosted, linux, x64, fast]
+    steps:
+      - name: Checkout Yosys
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          submodules: true
+
+      - name: Runtime environment
+        run: |
+          echo "procs=$(nproc)" >> $GITHUB_ENV
+
+      - name: Build Yosys
+        run: |
+          make config-clang
+          echo "ENABLE_VERIFIC := 1" >> Makefile.conf
+          echo "ENABLE_VERIFIC_EDIF := 1" >> Makefile.conf
+          echo "ENABLE_VERIFIC_LIBERTY := 1" >> Makefile.conf
+          echo "ENABLE_VERIFIC_YOSYSHQ_EXTENSIONS := 1" >> Makefile.conf
+          echo "ENABLE_CCACHE := 1" >> Makefile.conf
+          make -j${{ env.procs }} ENABLE_LTO=1
+
+      - name: Prepare docs
+        shell: bash
+        run:
+          make docs/prep TARGETS= EXTRA_TARGETS=
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: cmd-ref-${{ github.sha }}
+          path: |
+            docs/source/cmd
+            docs/source/generated
+            docs/source/_images
+            docs/source/code_examples
+
+      - name: Trigger RTDs build
+        uses: dfm/rtds-action@v1.1.0
+        with:
+          webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }}
+          webhook_token: ${{ secrets.RTDS_WEBHOOK_TOKEN }}
+          commit_ref: ${{ github.ref }}
diff --git a/.github/workflows/test-verific.yml b/.github/workflows/test-verific.yml
index 1b38b5f4254..7b55be7792c 100644
--- a/.github/workflows/test-verific.yml
+++ b/.github/workflows/test-verific.yml
@@ -1,10 +1,6 @@
 name: Build and run tests with Verific (Linux)
 
 on: [push, pull_request]
-# docs builds are needed for anything on main, any tagged versions, and any tag
-# or branch starting with docs-preview
-env:
-  is_docs_job: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/docs-preview') || startsWith(github.ref, 'refs/tags/') }}
 
 jobs:
   pre-job:
@@ -74,54 +70,3 @@ jobs:
         if: ${{ github.ref == 'refs/heads/main' }}
         run: |
           make -C sby run_ci
-
-  prepare-docs:
-    name: Generate docs artifact
-    needs: [pre-job, test-verific]
-    runs-on: [self-hosted, linux, x64, fast]
-    steps:
-      - name: Checkout Yosys
-        uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-          submodules: true
-
-      - name: Runtime environment
-        run: |
-          echo "procs=$(nproc)" >> $GITHUB_ENV
-
-      - name: Build Yosys
-        if: ${{ (needs.pre-job.outputs.should_skip != 'true') || env.is_docs_job }}
-        run: |
-          make config-clang
-          echo "ENABLE_VERIFIC := 1" >> Makefile.conf
-          echo "ENABLE_VERIFIC_EDIF := 1" >> Makefile.conf
-          echo "ENABLE_VERIFIC_LIBERTY := 1" >> Makefile.conf
-          echo "ENABLE_VERIFIC_YOSYSHQ_EXTENSIONS := 1" >> Makefile.conf
-          echo "ENABLE_CCACHE := 1" >> Makefile.conf
-          make -j${{ env.procs }} ENABLE_LTO=1
-
-      - name: Prepare docs
-        if: ${{ (needs.pre-job.outputs.should_skip != 'true') || env.is_docs_job }}
-        shell: bash
-        run:
-          make docs/prep TARGETS= EXTRA_TARGETS=
-
-      - name: Upload artifact
-        if: ${{ (needs.pre-job.outputs.should_skip != 'true') || env.is_docs_job }}
-        uses: actions/upload-artifact@v4
-        with:
-          name: cmd-ref-${{ github.sha }}
-          path: |
-            docs/source/cmd
-            docs/source/generated
-            docs/source/_images
-            docs/source/code_examples
-
-      - name: Trigger RTDs build
-        if: ${{ env.is_docs_job }}
-        uses: dfm/rtds-action@v1.1.0
-        with:
-          webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }}
-          webhook_token: ${{ secrets.RTDS_WEBHOOK_TOKEN }}
-          commit_ref: ${{ github.ref }}

From 25623b1010bcdb00f6b16724687aea63494d38b8 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Tue, 3 Sep 2024 11:45:00 +1200
Subject: [PATCH 14/17] ci: test-verific no longer needs special casing

---
 .github/workflows/test-verific.yml | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/test-verific.yml b/.github/workflows/test-verific.yml
index 7b55be7792c..43b68e06dca 100644
--- a/.github/workflows/test-verific.yml
+++ b/.github/workflows/test-verific.yml
@@ -11,13 +11,11 @@ jobs:
       - id: skip_check
         uses: fkirc/skip-duplicate-actions@v5
         with:
-          paths_ignore: '["**/README.md"]'
-          # don't cancel previous builds
-          cancel_others: 'false'
+          paths_ignore: '["**/README.md", "docs/**", "guidelines/**"]'
+          # cancel previous builds if a new commit is pushed
+          cancel_others: 'true'
           # only run on push *or* pull_request, not both
           concurrent_skipping: 'same_content_newer'
-          # we can skip testing if it has already passed
-          skip_after_successful_duplicate: 'true'
 
   test-verific:
     needs: pre-job

From 558f313a78ecdf3ad6692ac17a4aede4afe23a73 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Thu, 29 Aug 2024 10:43:01 +1200
Subject: [PATCH 15/17] Docs: Show todos in previews

That includes local builds.
Also fix release version numbers.
---
 docs/source/conf.py | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 2dc370c4b4d..723a0ea7fc4 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -61,15 +61,24 @@
 autosectionlabel_prefix_document = True
 autosectionlabel_maxdepth = 1
 
+# include todos for previews
+extensions.append('sphinx.ext.todo')
+
 # set version
 if os.getenv("READTHEDOCS"):
     rtds_version = os.getenv("READTHEDOCS_VERSION")
     if rtds_version == "latest":
         release = yosys_ver + "-dev"
+        todo_include_todos = False
+    elif rtds_version.startswith("yosys-"):
+        release = yosys_ver
+        todo_include_todos = False
     else:
         release = rtds_version
+        todo_include_todos = True
 else:
     release = yosys_ver
+    todo_include_todos = True
 
 # assign figure numbers
 numfig = True
@@ -84,10 +93,6 @@
 '''
 }
 
-# include todos during rewrite
-extensions.append('sphinx.ext.todo')
-todo_include_todos = False
-
 # custom cmd-ref parsing/linking
 sys.path += [os.path.dirname(__file__) + "/../"]
 extensions.append('util.cmdref')

From c0ce0b82a8382dca94fe501aa624a20198bbd10d Mon Sep 17 00:00:00 2001
From: "Emily (aiju)" <aiju@phicode.de>
Date: Thu, 22 Aug 2024 11:54:20 +0100
Subject: [PATCH 16/17] docs: gvpack on macos requires the file name to appear
 after the flags

---
 docs/source/code_examples/opt/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/code_examples/opt/Makefile b/docs/source/code_examples/opt/Makefile
index 4cb51e90bec..12c1c93b1c8 100644
--- a/docs/source/code_examples/opt/Makefile
+++ b/docs/source/code_examples/opt/Makefile
@@ -13,7 +13,7 @@ dots: $(DOTS)
 	$(YOSYS) $<
 
 %.dot: %_full.dot
-	gvpack -u $*_full.dot -o $@
+	gvpack -u -o $@ $*_full.dot
 
 .PHONY: clean
 clean:

From 89cbca4f44aec2912024a0f60d8a14244bf323f9 Mon Sep 17 00:00:00 2001
From: Miodrag Milanovic <mmicko@gmail.com>
Date: Tue, 3 Sep 2024 09:15:12 +0200
Subject: [PATCH 17/17] Add macOS instructions for latexpdf

---
 README.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/README.md b/README.md
index c806ec28340..d215d844201 100644
--- a/README.md
+++ b/README.md
@@ -638,6 +638,12 @@ build process for the website.  Or, run the following:
 
 	$ sudo apt install texlive-latex-base texlive-latex-extra latexmk
 
+Or for MacOS, using homebrew:
+
+  $ brew install basictex
+  $ sudo tlmgr update --self   
+  $ sudo tlmgr install collection-latexextra latexmk tex-gyre
+
 The Python package, Sphinx, is needed along with those listed in
 `docs/source/requirements.txt`: