From 4ea6119734fbf83493d1c4e48f86a342fe80c775 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 19 Jul 2024 14:23:31 +1200 Subject: [PATCH 1/4] cmdref: Move html only section inside cmd:def Fixes missing links in body and `??` in tag/command index. Update synth.rst to match. --- docs/source/index.rst | 2 +- docs/source/using_yosys/synthesis/synth.rst | 2 +- kernel/register.cc | 23 ++++++++++----------- 3 files changed, 13 insertions(+), 14 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 8b9cff86921..ab174242438 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -23,7 +23,7 @@ available, go to :ref:`commandindex`. - Search bar with live drop down suggestions for matching on title / autocompleting commands - Scroll the left sidebar to the current location on page load - - Also the formatting/linking in pdf is broken + - Also the formatting in pdf uses link formatting instead of code formatting .. todolist:: diff --git a/docs/source/using_yosys/synthesis/synth.rst b/docs/source/using_yosys/synthesis/synth.rst index 9014a924710..e3d82931bac 100644 --- a/docs/source/using_yosys/synthesis/synth.rst +++ b/docs/source/using_yosys/synthesis/synth.rst @@ -42,7 +42,7 @@ The following commands are executed by the `prep` command: .. literalinclude:: /cmd/prep.rst :start-at: begin: - :end-before: .. raw:: latex + :end-before: .. only:: latex :dedent: :doc:`/getting_started/example_synth` covers most of these commands and what diff --git a/kernel/register.cc b/kernel/register.cc index 311c9296104..d6e765ce416 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -812,11 +812,11 @@ struct HelpPass : public Pass { fprintf(f, "%s", title_line.c_str()); fprintf(f, "%s - %s\n", cmd.c_str(), title.c_str()); fprintf(f, "%s\n", title_line.c_str()); - fprintf(f, ".. raw:: latex\n\n \\begin{comment}\n\n"); // render html fprintf(f, ".. cmd:def:: %s\n", cmd.c_str()); - fprintf(f, " :title: %s\n\n", title.c_str()); + fprintf(f, " :title: %s\n\n", title.c_str()); + fprintf(f, " .. only:: html\n\n"); std::stringstream ss; std::string textcp = text; ss << text; @@ -852,32 +852,32 @@ struct HelpPass : public Pass { if (IsUsage) { if (stripped_line.compare(0, 4, "See ") == 0) { // description refers to another function - fprintf(f, "\n %s\n", stripped_line.c_str()); + fprintf(f, "\n %s\n", stripped_line.c_str()); } else { // usage should be the first line of help output - fprintf(f, "\n .. code:: yoscrypt\n\n %s\n\n ", stripped_line.c_str()); + fprintf(f, "\n .. code:: yoscrypt\n\n %s\n\n ", stripped_line.c_str()); WasDefinition = true; } IsUsage = false; } else if (IsIndent && NewUsage && (blank_count >= 2 || WasDefinition)) { // another usage block - fprintf(f, "\n .. code:: yoscrypt\n\n %s\n\n ", stripped_line.c_str()); + fprintf(f, "\n .. code:: yoscrypt\n\n %s\n\n ", stripped_line.c_str()); WasDefinition = true; def_strip_count = 0; } else if (IsIndent && IsDefinition && (blank_count || WasDefinition)) { // format definition term - fprintf(f, "\n\n .. code:: yoscrypt\n\n %s\n\n ", stripped_line.c_str()); + fprintf(f, "\n\n .. code:: yoscrypt\n\n %s\n\n ", stripped_line.c_str()); WasDefinition = true; def_strip_count = first_pos; } else { if (IsDedent) { - fprintf(f, "\n\n ::\n"); + fprintf(f, "\n\n ::\n"); def_strip_count = first_pos; } else if (WasDefinition) { - fprintf(f, " ::\n"); + fprintf(f, "::\n"); WasDefinition = false; } - fprintf(f, "\n %s", line.substr(def_strip_count, std::string::npos).c_str()); + fprintf(f, "\n %s", line.substr(def_strip_count, std::string::npos).c_str()); } blank_count = 0; @@ -885,13 +885,12 @@ struct HelpPass : public Pass { fputc('\n', f); // render latex - fprintf(f, ".. raw:: latex\n\n \\end{comment}\n\n"); fprintf(f, ".. only:: latex\n\n"); - fprintf(f, " ::\n\n"); + fprintf(f, " ::\n\n"); std::stringstream ss2; ss2 << textcp; for (std::string line; std::getline(ss2, line, '\n');) { - fprintf(f, " %s\n", line.c_str()); + fprintf(f, " %s\n", line.c_str()); } fclose(f); } From 5d14c3017e724f3693fb5e331952f76817924a41 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 19 Jul 2024 14:23:31 +1200 Subject: [PATCH 2/4] test-build.yml: Add test-docs-build Try use self hosted linux runner to build html and latexpdf to check for errors. Trying to use the build artifact didn't seem to work, so just run it on its own. Upload docs/build folder as artifact to enable review without having to build locally. Note: doesn't include verific, so will differ slightly from final published docs. --- .github/workflows/test-build.yml | 37 ++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/.github/workflows/test-build.yml b/.github/workflows/test-build.yml index e5aed6af3f0..4ac77a76591 100644 --- a/.github/workflows/test-build.yml +++ b/.github/workflows/test-build.yml @@ -189,3 +189,40 @@ jobs: shell: bash run: | make -C docs test -j${{ env.procs }} + + test-docs-build: + name: Try build docs + runs-on: [self-hosted, linux, x64] + needs: [pre_docs_job] + if: needs.pre_docs_job.outputs.should_skip != 'true' + strategy: + matrix: + docs-target: [html, latexpdf] + fail-fast: false + steps: + - name: Checkout Yosys + uses: actions/checkout@v4 + with: + submodules: true + + - name: Runtime environment + run: | + echo "procs=$(nproc)" >> $GITHUB_ENV + + - name: Build Yosys + run: | + make config-clang + echo "ENABLE_CCACHE := 1" >> Makefile.conf + make -j${{ env.procs }} + + - name: Build docs + shell: bash + run: | + make docs DOC_TARGET=${{ matrix.docs-target }} -j${{ env.procs }} + + - name: Store docs build artifact + uses: actions/upload-artifact@v4 + with: + name: docs-build-${{ matrix.docs-target }} + path: docs/build/ + retention-days: 7 From e5da0e341e5d468ffae02d09a68b2dd53b8f0628 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 17 Oct 2024 07:12:34 +1300 Subject: [PATCH 3/4] Makefile: Combine gen_images and gen_examples gen_images and gen_examples are never called on their own, CI scripts call make -C docs directly. Since calling them both in parallel seems to cause issues, let's not do that, and instead combine them into a singular `make docs/gen`. This should resolve the parallelism problems by making them sequential while still retaining the -j support. --- Makefile | 11 ++++------- docs/Makefile | 5 +++++ 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/Makefile b/Makefile index 91f48921e9c..217fc4761ca 100644 --- a/Makefile +++ b/Makefile @@ -996,12 +996,9 @@ docs/source/cell/word_add.rst: $(TARGETS) $(EXTRA_TARGETS) docs/source/generated/cells.json: docs/source/generated $(TARGETS) $(EXTRA_TARGETS) $(Q) ./$(PROGRAM_PREFIX)yosys -p 'help -dump-cells-json $@' -PHONY: docs/gen_examples docs/gen_images docs/guidelines docs/usage docs/reqs -docs/gen_examples: $(TARGETS) - $(Q) $(MAKE) -C docs examples - -docs/gen_images: $(TARGETS) - $(Q) $(MAKE) -C docs images +PHONY: docs/gen docs/guidelines docs/usage docs/reqs +docs/gen: $(TARGETS) + $(Q) $(MAKE) -C docs gen DOCS_GUIDELINE_FILES := GettingStarted CodingStyle DOCS_GUIDELINE_SOURCE := $(addprefix guidelines/,$(DOCS_GUIDELINE_FILES)) @@ -1037,7 +1034,7 @@ docs/reqs: $(Q) $(MAKE) -C docs reqs .PHONY: docs/prep -docs/prep: docs/source/cmd/abc.rst docs/source/generated/cells.json docs/gen_examples docs/gen_images docs/guidelines docs/usage +docs/prep: docs/source/cmd/abc.rst docs/source/generated/cells.json docs/gen docs/guidelines docs/usage DOC_TARGET ?= html docs: docs/prep diff --git a/docs/Makefile b/docs/Makefile index 6dbf6f4902b..a8874bb833e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -252,6 +252,11 @@ images: $(MAKE) -C source/_images $(MAKE) -C source/_images convert +.PHONY: gen +gen: + $(MAKE) examples + $(MAKE) images + .PHONY: reqs reqs: $(PYTHON) -m pip install -r source/requirements.txt From d1c6699125629836ea1699b2c1bcb520e96ef5fc Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 17 Oct 2024 07:15:11 +1300 Subject: [PATCH 4/4] test-docs-build: Use fast runner --- .github/workflows/test-build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test-build.yml b/.github/workflows/test-build.yml index 4ac77a76591..2c4deff23ad 100644 --- a/.github/workflows/test-build.yml +++ b/.github/workflows/test-build.yml @@ -192,7 +192,7 @@ jobs: test-docs-build: name: Try build docs - runs-on: [self-hosted, linux, x64] + runs-on: [self-hosted, linux, x64, fast] needs: [pre_docs_job] if: needs.pre_docs_job.outputs.should_skip != 'true' strategy: