From 3b63ab07ae289397573d32f2851cd78aedeeea94 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Fri, 16 Aug 2024 10:43:51 +1200
Subject: [PATCH 1/2] docs: Build RTD artifacts directly

Use rtds-action instead of yosys-cmd-ref repo.
Add rtds_action to docs configuration.
Add `.readthedocs.yaml`.
Update `DOCS_USAGE_` make target to be able to use pre-generated executables without forcing a remake.
---
 .github/workflows/test-verific.yml | 71 ++++++++++++++++++++----------
 .readthedocs.yaml                  | 19 ++++++++
 Makefile                           |  8 ++--
 docs/source/conf.py                |  8 +++-
 docs/source/requirements.txt       |  1 +
 5 files changed, 78 insertions(+), 29 deletions(-)
 create mode 100644 .readthedocs.yaml

diff --git a/.github/workflows/test-verific.yml b/.github/workflows/test-verific.yml
index e08f7bd2e..d89634009 100644
--- a/.github/workflows/test-verific.yml
+++ b/.github/workflows/test-verific.yml
@@ -47,30 +47,6 @@ jobs:
         run: |
           make install DESTDIR=${GITHUB_WORKSPACE}/.local PREFIX=
 
-      - name: Checkout Documentation
-        if: ${{ github.ref == 'refs/heads/main' }}
-        uses: actions/checkout@v4
-        with:
-          path: 'yosys-cmd-ref'
-          repository: 'YosysHQ-Docs/yosys-cmd-ref'
-          fetch-depth: 0
-          token: ${{ secrets.CI_DOCS_UPDATE_PAT }}
-          persist-credentials: true
-
-      - name: Update documentation
-        if: ${{ github.ref == 'refs/heads/main' }}
-        run: |
-          make docs
-          rm -rf docs/build
-          cd yosys-cmd-ref
-          rm -rf *
-          git checkout README.md
-          cp -R ../docs/* .
-          rm -rf util/__pycache__
-          git add -A .
-          git diff-index --quiet HEAD || git commit -m "Update"
-          git push
-
       - name: Checkout SBY
         uses: actions/checkout@v4
         with:
@@ -94,3 +70,50 @@ jobs:
         if: ${{ github.ref == 'refs/heads/main' }}
         run: |
           make -C sby run_ci
+
+  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]
+    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/source/cmd/abc.rst docs/gen_examples docs/gen_images docs/guidelines docs/usage docs/reqs 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/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 000000000..cb700dc1c
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,19 @@
+# .readthedocs.yaml
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+    os: ubuntu-22.04
+    tools:
+        python: '3.12'
+
+formats:
+  - pdf
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - requirements: docs/source/requirements.txt
diff --git a/Makefile b/Makefile
index a2803ed59..44c77eeaa 100644
--- a/Makefile
+++ b/Makefile
@@ -984,8 +984,8 @@ docs/guidelines docs/source/generated:
 
 # some commands return an error and print the usage text to stderr
 define DOC_USAGE_STDERR
-docs/source/generated/$(1): $(PROGRAM_PREFIX)$(1) docs/source/generated
-	-$(Q) ./$$< --help 2> $$@
+docs/source/generated/$(1): $(TARGETS) docs/source/generated
+	-$(Q) ./$(PROGRAM_PREFIX)$(1) --help 2> $$@
 endef
 DOCS_USAGE_STDERR := yosys-config yosys-filterlib
 
@@ -998,8 +998,8 @@ $(foreach usage,$(DOCS_USAGE_STDERR),$(eval $(call DOC_USAGE_STDERR,$(usage))))
 
 # others print to stdout
 define DOC_USAGE_STDOUT
-docs/source/generated/$(1): $(PROGRAM_PREFIX)$(1) docs/source/generated
-	$(Q) ./$$< --help > $$@
+docs/source/generated/$(1): $(TARGETS) docs/source/generated
+	$(Q) ./$(PROGRAM_PREFIX)$(1) --help > $$@
 endef
 DOCS_USAGE_STDOUT := yosys yosys-smtbmc yosys-witness
 $(foreach usage,$(DOCS_USAGE_STDOUT),$(eval $(call DOC_USAGE_STDOUT,$(usage))))
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 2fdd43a31..23efe2b43 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -41,7 +41,13 @@ html_static_path = ['_static', "_images"]
 pygments_style = 'colorful'
 highlight_language = 'none'
 
-extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.bibtex']
+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"]
 
 # Ensure that autosectionlabel will produce unique names
 autosectionlabel_prefix_document = True
diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt
index 74c8dd090..dbba55832 100644
--- a/docs/source/requirements.txt
+++ b/docs/source/requirements.txt
@@ -1,2 +1,3 @@
 furo
 sphinxcontrib-bibtex
+rtds-action

From 7bd3c7b968432896771d2294103bd7a8b88487d7 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Fri, 16 Aug 2024 10:43:51 +1200
Subject: [PATCH 2/2] Fix test-verific.yml

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

diff --git a/.github/workflows/test-verific.yml b/.github/workflows/test-verific.yml
index d89634009..b76718c21 100644
--- a/.github/workflows/test-verific.yml
+++ b/.github/workflows/test-verific.yml
@@ -3,7 +3,7 @@ name: Build and run tests with Verific (Linux)
 on: [push, pull_request]
 
 jobs:
-  pre_job:
+  pre-job:
     runs-on: ubuntu-latest
     outputs:
       should_skip: ${{ steps.skip_check.outputs.should_skip }}
@@ -20,8 +20,8 @@ jobs:
           skip_after_successful_duplicate: 'false'
 
   test-verific:
-    needs: pre_job
-    if: needs.pre_job.outputs.should_skip != 'true'
+    needs: pre-job
+    if: needs.pre-job.outputs.should_skip != 'true'
     runs-on: [self-hosted, linux, x64]
     steps:
       - name: Checkout Yosys
@@ -73,8 +73,8 @@ jobs:
 
   prepare-docs:
     name: Generate docs artifact
-    needs: pre_job, test-verific
-    if: needs.pre_job.outputs.should_skip != 'true'
+    needs: [pre-job, test-verific]
+    if: needs.pre-job.outputs.should_skip != 'true'
     runs-on: [self-hosted, linux, x64]
     steps:
       - name: Checkout Yosys