Merge pull request #3907 from YosysHQ/krys/docs

Manual rewrite and presentation merge

Author: nakengelhardt

.github/workflows/test-docs.yml

@@ -0,0 +1,42 @@
+name: Build and test doc code samples
+
+on:
+  pull_request:
+    branches:
+    - master
+
+jobs:
+  test-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Dependencies
+        shell: bash
+        run: |
+          sudo apt-get update
+          sudo apt-get install gperf build-essential bison flex libreadline-dev gawk tcl-dev libffi-dev git graphviz xdot pkg-config python3 libboost-system-dev libboost-python-dev libboost-filesystem-dev zlib1g-dev
+
+      - name: Setup GCC
+        uses: Dup4/actions-setup-gcc@v1
+
+      - name: Runtime environment
+        shell: bash
+        env:
+          WORKSPACE: ${{ github.workspace }}
+        run: |
+          echo "GITHUB_WORKSPACE=`pwd`" >> $GITHUB_ENV
+          echo "$GITHUB_WORKSPACE/.local/bin" >> $GITHUB_PATH
+          echo "procs=$(nproc)" >> $GITHUB_ENV
+
+      - name: Checkout Yosys
+        uses: actions/checkout@v3
+
+      - name: Build yosys
+        shell: bash
+        run: |
+          make config-gcc
+          make -j${{ env.procs }}
+
+      - name: Run tests
+        shell: bash
+        run: |
+          make -C docs test -j${{ env.procs }}

.github/workflows/test-linux.yml

@@ -112,6 +112,13 @@ jobs:
           make config-${CC%%-*}
           make -j${{ env.procs }} CXXSTD=${{ matrix.cpp_std }} CC=$CC CXX=$CC LD=$CC
 
+      - name: Store build artifact
+        if: (matrix.cpp_std == 'c++11') && (matrix.compiler == 'gcc-11')
+        uses: actions/upload-artifact@v4
+        with:
+          name: compiled-yosys
+          path: yosys
+
       - name: Run tests
         if: (matrix.cpp_std == 'c++11') && (matrix.compiler == 'gcc-11')
         shell: bash

CODEOWNERS

@@ -18,6 +18,7 @@ passes/techmap/flowmap.cc      @whitequark
 passes/opt/opt_lut.cc          @whitequark
 passes/techmap/abc9*.cc        @eddiehung @Ravenslofty
 backends/aiger/xaiger.cc       @eddiehung
+docs/                          @KrystalDelusion
 
 
 ## External Contributors

Makefile

@@ -971,17 +971,27 @@ docs/source/cmd/abc.rst: $(TARGETS) $(EXTRA_TARGETS)
 	mkdir -p docs/source/cmd
 	./$(PROGRAM_PREFIX)yosys -p 'help -write-rst-command-reference-manual'
 
-PHONY: docs/gen_images docs/guidelines
+PHONY: docs/gen_examples docs/gen_images docs/guidelines docs/usage
+docs/gen_examples:
+	$(Q) $(MAKE) -C docs examples
+
 docs/gen_images:
-	$(Q) $(MAKE) -C docs/images all
+	$(Q) $(MAKE) -C docs images
 
 DOCS_GUIDELINE_FILES := GettingStarted CodingStyle
 docs/guidelines:
 	$(Q) mkdir -p docs/source/temp
 	$(Q) cp -f $(addprefix guidelines/,$(DOCS_GUIDELINE_FILES)) docs/source/temp
 
+# many of these will return an error which can be safely ignored, so we prefix
+# the command with a '-'
+DOCS_USAGE_PROGS := yosys yosys-config yosys-filterlib yosys-abc yosys-smtbmc yosys-witness
+docs/usage: $(addprefix docs/source/temp/,$(DOCS_USAGE_PROGS))
+docs/source/temp/%: docs/guidelines
+	-$(Q) ./$(PROGRAM_PREFIX)$* --help > $@ 2>&1
+
 DOC_TARGET ?= html
-docs: docs/source/cmd/abc.rst docs/gen_images docs/guidelines
+docs: docs/source/cmd/abc.rst docs/gen_examples docs/gen_images docs/guidelines docs/usage
 	$(Q) $(MAKE) -C docs $(DOC_TARGET)
 
 clean:
@@ -1000,8 +1010,6 @@ clean:
 	rm -f tests/svinterfaces/*.log_stdout tests/svinterfaces/*.log_stderr tests/svinterfaces/dut_result.txt tests/svinterfaces/reference_result.txt tests/svinterfaces/a.out tests/svinterfaces/*_syn.v tests/svinterfaces/*.diff
 	rm -f  tests/tools/cmp_tbdata
 	$(MAKE) -C docs clean
-	$(MAKE) -C docs/images clean
-	rm -rf docs/source/cmd docs/util/__pycache__
 
 clean-abc:
 	$(MAKE) -C abc DEP= clean

README.md

@@ -610,10 +610,12 @@ Simply visit https://yosys.readthedocs.io/en/latest/ instead.
 In addition to those packages listed above for building Yosys from source, the
 following are used for building the website: 
 
-	$ sudo apt-get install pdf2svg faketime
+	$ sudo apt install pdf2svg faketime
 
 PDFLaTeX, included with most LaTeX distributions, is also needed during the
-build process for the website.
+build process for the website.  Or, run the following:
+
+	$ sudo apt install texlive-latex-base texlive-latex-extra latexmk
 
 The Python package, Sphinx, is needed along with those listed in
 `docs/source/requirements.txt`:

docs/.gitignore

@@ -1,11 +1,9 @@
 /build/
 /source/cmd
 /source/temp
-/images/*.log
-/images/*.aux
-/images/*.pdf
-/images/*.svg
-/images/011/*.log
-/images/011/*.aux
-/images/011/*.pdf
-/images/011/*.svg
+/source/_images/**/*.log
+/source/_images/**/*.aux
+/source/_images/**/*.pdf
+/source/_images/**/*.svg
+/source/_images/**/*.dot
+/source/_images/code_examples

docs/Makefile

@@ -45,8 +45,10 @@ help:
 	@echo "  dummy      to check syntax errors of document sources"
 
 .PHONY: clean
-clean:
+clean: clean-examples
 	rm -rf $(BUILDDIR)/*
+	rm -rf source/cmd util/__pycache__
+	$(MAKE) -C source/_images clean
 
 .PHONY: html
 html:
@@ -224,3 +226,27 @@ dummy:
 	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
 	@echo
 	@echo "Build finished. Dummy builder generates no files."
+
+PYTHON ?= python3
+
+.PHONY: test test-examples test-macros examples
+test: test-examples test-macros
+
+FORCE:
+Makefile-%: FORCE
+	$(MAKE) -C $(@D) $(*F)
+
+CODE_EXAMPLES := $(wildcard source/code_examples/*/Makefile)
+TEST_EXAMPLES := $(addsuffix -all,$(CODE_EXAMPLES))
+CLEAN_EXAMPLES := $(addsuffix -clean,$(CODE_EXAMPLES))
+test-examples: $(TEST_EXAMPLES)
+clean-examples: $(CLEAN_EXAMPLES)
+examples: $(TEST_EXAMPLES)
+
+test-macros:
+	$(PYTHON) tests/macro_commands.py
+
+.PHONY: images
+images:
+	$(MAKE) -C source/_images
+