From 9f4d5ff71ffbac166e15bbd7b9c1ed22f7e53e72 Mon Sep 17 00:00:00 2001 From: Jorge Marques Date: Tue, 21 Nov 2023 09:56:25 -0300 Subject: [PATCH] docs: General improvements Import aiohttp and asyncio only when needed. Better warning for unknown signals, params. Use pattern matching in regmap parsing. Fixup bundle count. Add lists clarification to guidelines. Enforce #1229 rules. Clean-up Makefile. Use non-breaking hyphen. Signed-off-by: Jorge Marques --- docs/Makefile | 63 ----------------------------- docs/extensions/adi_hdl_parser.py | 39 ++++++++++-------- docs/extensions/adi_links.py | 10 +++-- docs/library/axi_dmac/index.rst | 16 ++++---- docs/projects/template/index.rst | 22 ++++++---- docs/requirements.txt | 1 + docs/sources/custom.css | 3 -- docs/user_guide/docs_guidelines.rst | 26 ++++++++++++ 8 files changed, 78 insertions(+), 102 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 58c2f28b8..955dbcdbe 100755 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,72 +5,9 @@ SOURCEDIR = . BUILDDIR = _build help: - @echo "For help about the container instance, do \`make container-help\`" @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) .PHONY: help Makefile %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -#------------------------------------------------------------------------------ -# Container commands -#------------------------------------------------------------------------------ - -CONTAINER_IMG ?=hdl-docs -CONTAINER_ENGINE =podman -CONTAINER_REPO =${CONTAINER_IMG} -CONTAINER_IMAGE =${CONTAINER_IMG}_build -CONTAINER_VERSION ?=0.1 -CONTAINER_SHELL ?=bash -l -CONTAINER_RUN_EXTRA ?= -CONTAINER_FORMAT =$(if $(filter podman,${CONTAINER_ENGINE}),--format docker,) - -IF_CONTAINER_RUNS=$(shell ${CONTAINER_ENFINE} container inspect -f '{{.State.Running}}' ${CONTAINER_IMAGE} 2>/dev/null) - -CONTAINER_RUN_PARAMS = -it --rm --name=${CONTAINER_IMG} \ - --name=${CONTAINER_IMAGE} \ - --workdir=/${CONTAINER_IMG} \ - --mount type=bind,source=${CURDIR}/../,target=/${CONTAINER_IMG} \ - ${CONTAINER_RUN_EXTRA} \ - ${CONTAINER_REPO}/${CONTAINER_IMAGE}:${CONTAINER_VERSION} - -container-login: - @if [ "${IF_CONTAINER_RUNS}" != "true" ]; then \ - ${CONTAINER_ENGINE} run ${CONTAINER_RUN_PARAMS} \ - ${CONTAINER_SHELL}; \ - else \ - ${CONTAINER_ENGINE} exec -it ${CONTAINER_IMAGE} \ - ${CONTAINER_SHELL}; \ - fi - -container-build: - @printf "Building container image\n" - @${CONTAINER_ENGINE} build --no-cache=true ${CONTAINER_FORMAT} -t ${CONTAINER_REPO}/${CONTAINER_IMAGE}:${CONTAINER_VERSION} -f ./Containerfile . - - -container-html: - @${CONTAINER_ENGINE} run ${CONTAINER_RUN_PARAMS} ${CONTAINER_SHELL} -c \ - "source /.venv/bin/activate ; cd docs ; make html" - -container-pdf: - @${CONTAINER_ENGINE} run ${CONTAINER_RUN_PARAMS} ${CONTAINER_SHELL} -c \ - "source /.venv/bin/activate ; cd docs ; make latexpdf" - -container-clean: - @${CONTAINER_ENGINE} run ${CONTAINER_RUN_PARAMS} ${CONTAINER_SHELL} -c \ - "source /.venv/bin/activate ; cd docs ; make clean" - -.PHONY: container-build container-login container-html container-pdf container-clean - -container-help: - @printf "The container commands allow to use a container to build the documentation.\n" - @printf "Both podman and docker are supported, change the CONTAINER_ENGINE variable to select which to use.\n\n" - @printf "Usage: make [options]\n" - @printf "\ -Options:\n\ - container-build Build the container image with dependencies (do once).\n\ - container-login Access the container shell.\n\ - container-html Build html documentation.\n\ - container-latexpdf Build pdf documentation.\n\ -\n" diff --git a/docs/extensions/adi_hdl_parser.py b/docs/extensions/adi_hdl_parser.py index 75c7954f3..f5df14794 100644 --- a/docs/extensions/adi_hdl_parser.py +++ b/docs/extensions/adi_hdl_parser.py @@ -4,6 +4,8 @@ ############################################################################### import os.path +import contextlib +import re from docutils import nodes from docutils.statemachine import ViewList from docutils.parsers.rst import Directive, directives @@ -13,7 +15,6 @@ from lxml import etree from adi_hdl_static import hdl_strings from uuid import uuid4 from hashlib import sha1 -import contextlib logger = logging.getLogger(__name__) @@ -340,7 +341,7 @@ class directive_interfaces(directive_base): for tag in description: if tag not in bs and tag not in pr: - logger.warning(f"Signal {tag} defined in the directive does not exist in the source code!") + logger.warning(f"Signal {tag} defined in the directive does not exist in the IP-XACT (component.xml)!") return subnode @@ -523,7 +524,7 @@ class directive_parameters(directive_base): for tag in description: if tag not in parameter: - logger.warning(f"{tag} defined in the directive does not exist in the source code!") + logger.warning(f"{tag} defined in the directive does not exist in the IP-XACT (component.xml)!") return table @@ -893,21 +894,25 @@ def manage_hdl_regmaps(env, docnames): if not os.path.isfile(f): del rm[lib] # Inconsistent naming convention, need to parse all in directory. - files = [] + regmaps = [] for (dirpath, dirnames, filenames) in os.walk("regmap"): - files.extend(filenames) - break - regmaps = [f.replace('adi_regmap_','').replace('.txt','') for f in files] - for reg_name in regmaps: - ctime = os.path.getctime(f"regmap/adi_regmap_{reg_name}.txt") - if reg_name in rm and rm[reg_name]['ctime'] < ctime: - for o in rm[reg_name]['owners']: - if o not in docnames: - docnames.append(o) - if reg_name in rm and rm[reg_name]['ctime'] >= ctime: - pass - else: - rm[reg_name] = parse_hdl_regmap(reg_name, ctime) + for file in filenames: + m = re.search("adi_regmap_(\w+)\.txt", file) + if not bool(m): + continue + + reg_name = m.group(1) + regmaps.extend(reg_name) + + ctime = os.path.getctime(f"regmap/{file}") + if reg_name in rm and rm[reg_name]['ctime'] < ctime: + for o in rm[reg_name]['owners']: + if o not in docnames: + docnames.append(o) + if reg_name in rm and rm[reg_name]['ctime'] >= ctime: + pass + else: + rm[reg_name] = parse_hdl_regmap(reg_name, ctime) def manage_hdl_artifacts(app, env, docnames): libraries = [[k.replace('/index',''), k] for k in env.found_docs if k.find('library/') == 0] diff --git a/docs/extensions/adi_links.py b/docs/extensions/adi_links.py index 3257834c5..8f4303607 100644 --- a/docs/extensions/adi_links.py +++ b/docs/extensions/adi_links.py @@ -3,11 +3,9 @@ ### SPDX short identifier: ADIBSD ############################################################################### +import subprocess from docutils import nodes from sphinx.util import logging -import subprocess -import asyncio -import aiohttp logger = logging.getLogger(__name__) validate_links_user_agent = 'Status resolver (Python/Sphinx)' @@ -151,6 +149,10 @@ def validate_links(app, env): logger.info(f"Skipping {len(env.links)} URLs checks-ups. Set validate_links to True to enable this.") return + global asyncio, aiohttp + import asyncio + import aiohttp + asyncio.run( async_validate_links(app, env) ) @@ -177,7 +179,7 @@ async def async_validate_links(app, env): step = 25 links = list(env.links) - leng = total%step+2 if total%step != 0 else total%step+1 + leng = int(total/step)+1 if total%step != 0 else int(total/step) for i in range(0, leng): cur = i*step end = total if (i+1)*step > total else (i+1)*step diff --git a/docs/library/axi_dmac/index.rst b/docs/library/axi_dmac/index.rst index d080a29cd..d28dc5bae 100644 --- a/docs/library/axi_dmac/index.rst +++ b/docs/library/axi_dmac/index.rst @@ -591,7 +591,7 @@ the following order: * - Size - Name - Description - * - 32-bit + * - 32‑bit - flags - | This field includes 2 control bits: @@ -600,25 +600,25 @@ the following order: next DMA descriptor pointed to by ``next_sg_addr`` will be loaded. * bit1: if set, an end-of-transfer interrupt will be raised after the memory segment pointed to by this descriptor has been transferred. - * - 32-bit + * - 32‑bit - id - This field corresponds to an identifier of the descriptor. - * - 64-bit + * - 64‑bit - dest_addr - This field contains the destination address of the transfer. - * - 64-bit + * - 64‑bit - src_addr - This field contains the source address of the transfer. - * - 64-bit + * - 64‑bit - next_sg_addr - This field contains the address of the next descriptor. - * - 32-bit + * - 32‑bit - y_len - This field contains the number of rows to transfer, minus one. - * - 32-bit + * - 32‑bit - x_len - This field contains the number of bytes to transfer, minus one. - * - 32-bit + * - 32‑bit - src_stride - This field contains the number of bytes between the start of one row and the next row for the source address. diff --git a/docs/projects/template/index.rst b/docs/projects/template/index.rst index e4f1abf81..f6be92f92 100644 --- a/docs/projects/template/index.rst +++ b/docs/projects/template/index.rst @@ -87,19 +87,22 @@ Block design Block diagram ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -\**\* MUST HAVE \**\* The data path and clock domains are depicted in -the below diagram: - -\*\* TIP: upload the .svg file for the diagram to have high quality \*\* - If the project has multiple ways of configuration, then make subsections to this section and show the default configuration and some other popular modes. +\**\* KEEP THIS PARAGRAPH \**\* +The data path and clock domains are depicted in the below diagram: + .. image:: ../ad9783_ebz/ad9783_zcu102_block_diagram.svg :width: 800 :align: center :alt: AD9783-EBZ/ZCU102 block diagram +\*\* MUST: Use SVG format for the diagram \*\* + +\*\* TIP: Block diagrams should contain subtitles only if there are at least two +different diagrams \*\* + Configuration modes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -146,8 +149,7 @@ Clock scheme - SYSREF clocks are LVDS - ADCCLK and REFCLK are LVPECL -\*\* ADD IMAGE IF APPLIES! TIP: upload the .svg file for the diagram to have -high quality \*\* +\*\* ADD IMAGE IF APPLIES! MUST: Use SVG format \*\* **\*DESCRIBE OTHER COMPONENTS FROM THE PROJECT, EX: SYNCHRONA**\ \* @@ -185,6 +187,7 @@ chains are merged together and transferred to the DDR with a single DMA. CPU/Memory interconnects addresses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +\**\* KEEP THIS PARAGRAPH \**\* The addresses are dependent on the architecture of the FPGA, having an offset added to the base address from HDL (see more at :ref:`architecture`). @@ -197,6 +200,8 @@ some IPs are instatiated and some are not. Check-out the table below to find out the conditions. +\*\* MUST: Hexadecimal addresses are written in caps and separated by an underscore. \*\* + ==================== ================================= =============== =========== ============ Instance Depends on parameter Zynq/Microblaze ZynqMP Versal ==================== ================================= =============== =========== ============ @@ -293,6 +298,9 @@ GPIOs - 117:86 - 141:110 +\*\* MUST: GPIOs should be listed in descending order and should have the number +of bits specified next to their name \*\* + Interrupts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/requirements.txt b/docs/requirements.txt index a00fccc2e..1e2a4a33a 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,5 @@ sphinx +regex lxml furo wavedrom diff --git a/docs/sources/custom.css b/docs/sources/custom.css index e88b52fb8..f127e42b4 100755 --- a/docs/sources/custom.css +++ b/docs/sources/custom.css @@ -60,9 +60,6 @@ table.regmap { table.regmap .caption-text{ font-size: 1rem; } -td { - min-width: 4em; -} th, td.type { white-space: nowrap; } diff --git a/docs/user_guide/docs_guidelines.rst b/docs/user_guide/docs_guidelines.rst index e11003572..55d10b276 100644 --- a/docs/user_guide/docs_guidelines.rst +++ b/docs/user_guide/docs_guidelines.rst @@ -128,6 +128,32 @@ an option, you shall remove it and export in the *grid* table format. Now you only have to adjust the widths and give the final touches, like using the correct directives and roles. +Lists +-------------------------------------------------------------------------------- + +Unordered lists use ``*`` or ``-`` and ordered lists ``#.``. + +Child items must be aligned with the first letter of the parent item, that means, +2 spaces for unordered list and 3 spaces for ordered lists, for example: + +.. code-block:: rst + + #. Parent ordered item. + + * Child unordeded item. + + #. Child ordered item. + #. Child ordered item. + +Renders as: + +#. Parent numbered item. + + * Child unordered item. + + #. Child ordered item. + #. Child ordered item. + Code --------------------------------------------------------------------------------