Better docs builds

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

.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
+          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 have special actions when running on main, so this should be off
-          skip_after_successful_duplicate: 'false'
 
   test-verific:
     needs: pre-job
@@ -70,51 +68,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]
-    if: needs.pre-job.outputs.should_skip != 'true'
-    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/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
-        if: ${{ github.ref == 'refs/heads/main' }}
-        uses: dfm/[email protected]
-        with:
-          webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }}
-          webhook_token: ${{ secrets.RTDS_WEBHOOK_TOKEN }}
-          commit_ref: ${{ github.ref }}

.readthedocs.yaml

@@ -13,6 +13,7 @@ formats:
 
 sphinx:
   configuration: docs/source/conf.py
+  fail_on_warning: true
 
 python:
   install:

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/reqs
+docs: docs/prep
 	$(Q) $(MAKE) -C docs $(DOC_TARGET)
 
 clean:

README.md

@@ -629,11 +629,21 @@ 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:
 
 	$ 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`:
 

docs/Makefile

@@ -250,6 +250,7 @@ test-macros:
 .PHONY: images
 images:
 	$(MAKE) -C source/_images
+	$(MAKE) -C source/_images convert
 
 .PHONY: reqs
 reqs:

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

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:

docs/source/conf.py

@@ -41,23 +41,44 @@
 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
 autosectionlabel_maxdepth = 1
 
+# include todos for previews
+extensions.append('sphinx.ext.todo')
+
 # 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"
+        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
@@ -72,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')

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
 

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`

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``.