Merge pull request #4376 from YosysHQ/krys/docs_cmd_ref

Docs: Use formatted cmd ref in pdf

.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, fast]
+    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

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

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

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

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

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,46 +852,45 @@ 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;
 		}
 		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);
 	}