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

@@ -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/[email protected]
+        with:
+          webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }}
+          webhook_token: ${{ secrets.RTDS_WEBHOOK_TOKEN }}
+          commit_ref: ${{ github.ref }}

.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

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))))

docs/source/conf.py

@@ -41,7 +41,13 @@
 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

docs/source/requirements.txt

@@ -1,2 +1,3 @@
 furo
 sphinxcontrib-bibtex
+rtds-action