.. _docs_guidelines: Documentation guidelines ================================================================================ A brief set-of-rules for the documentation. .. note:: The old wiki uses `dokuwiki `_. When importing text from there, consider the automated options that are provided in this page to convert it to reST. Templates -------------------------------------------------------------------------------- Templates are available: * :git-hdl:`docs/library/template_ip` (:ref:`rendered `). * :git-hdl:`docs/library/template_framework` (:ref:`rendered `). * :git-hdl:`docs/projects/template` (:ref:`rendered `). Remove the ``:orphan:`` in the first line, it is to hide the templates from the `TOC tree `_. Indentation -------------------------------------------------------------------------------- Directives are indented with 3 space, which is Sphinx's default. At code directives, the code keeps its original indentation (e.g. 2 spaces for Verilog code), but is offset by 3 spaces at the beginning of every line, to instruct Sphinx the beginning and end of the code directive. Table of contents -------------------------------------------------------------------------------- The relation between pages are created with the ``toctree`` directive, which allows to generate the table of contents and navigation bars. The ``toctree`` directive has the following format: .. code:: rst .. toctree:: :caption: Caption :hidden: Custom title For pages with shorter titles, such as libraries, the label is inherited from the page itself, for example: .. code:: rst .. toctree:: :caption: Libraries :hidden: library/axi_dmac/index library/spi_engine/index And for pages with long titles, such as projects, overwrite the full title with a custom title, e.g: .. code:: rst .. toctree:: :caption: Projects :hidden: AD7616-SDZ This way, only "AD7616-SDZ" will be displayed in the page navigation bar instead of "AD7616-SDZ HDL project". References -------------------------------------------------------------------------------- References have the format ``library/project context``, e.g. :code:`:ref:\`spi_engine execution\`` renders as :ref:`spi_engine execution`. Notice how neither *library* nor *project* are present in the label, since there is no naming collision between libraries or projects (no project will ever be named *axi_dmac*). Also, for project, libraries and IPs, the names should be exactly the name of its folders, e.g. ``axi_pwm_gen`` and not ``axi-pwm-gen`` or ``AXI_PWM_GEN``, this helps avoid broken references. For resources without a particular source code file/folder, prefer hyphen ``-`` separation, for example, ``spi_engine control-interface`` instead of ``spi_engine control_interface``. Text width -------------------------------------------------------------------------------- Each line must be less than 80 columns wide. You can use the :code:`fold` command to break the lines of the imported text while respecting word-breaks: .. code:: bash cat imported.txt | fold -sw 80 > imported.rst Or use :code:`pandoc`: .. code:: bash pandoc imported.txt -f dokuwiki -t rst --columns=80 -s -o imported.rst Tables -------------------------------------------------------------------------------- Prefer `list-tables `_ and imported `csv-tables `_ (using the file option), because they are faster to create, easier to maintain and the 80 column-width rule can be respected with list-tables. You can use the following command: .. code:: bash pandoc imported.txt -f dokuwiki -t rst --columns=80 -s -o imported.rst --list-tables The :code:`list-tables` parameter requires *pandoc-types* >= 1.23, if it is not 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. Code -------------------------------------------------------------------------------- Prefer `code-blocks `_ to `code `_ directives, because code-blocks have more options, such as showing line numbers and emphasizing lines. For example, .. code:: rst .. code-block:: python :linenos: :emphasize-lines: 2 def hello_world(): string = "Hello world" print(string) Renders as .. code-block:: python :linenos: :emphasize-lines: 2 def hello_world(): string = "Hello world" print(string) Images -------------------------------------------------------------------------------- Prefer the SVG format for images, and save it as *Optimized SVG* in `inkscape `_ to use less space. Store them in a hierarchically, do not use ``images`` subdirectories. The idea is to have simpler relative paths, for example, e.g.: .. code:: rst .. image: ad2234_sdz_schematic.svg Instead of overly complicated paths like: .. code:: rst .. image: ../../project/images/ad2234_sdz/ad2234_sdz_schematic.svg In general, this avoids dangling artifacts and keeps the documentation simple. Vivado block-diagrams ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Vivado block-diagrams can be exported as PDF and then converted to SVG with Inkscape. See :ref:`spi_engine tutorial` for a "final result" example. Vivado waveform data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There is no way to export Vivado waveform data as vectors. Therefore, the recommended method is to take a PNG screenshot and use `GIMP `_ to export as **8bpc RGB** with all metadata options disabled. .. note:: Always use the *Export As..* ``Ctrl+Shift+E`` option. To reduce even further the size, you can use *Color > Dither..* to reduce the number of colors in the PNG. Saving as greyscale also reduces the PNG size, but might reduce readability and it is not recommended. Third-party directives and roles -------------------------------------------------------------------------------- Third-party tools are used to expand Sphinx functionality, if you haven't already, do: .. code:: bash pip install -r requirements.txt Symbolator directive ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ `Symbolator `_ is a tool to generate component diagrams. Custom directives and roles -------------------------------------------------------------------------------- To expand Sphinx functionality beyond existing tools, custom directives and roles have been written, which are located in the *docs/extensions* folder. Extensions are straight forward to create, if some functionality is missing, consider requesting or creating one. .. note:: Link-like roles use the :code:`:role:\`text \`` synthax, like external links, but without the undescore in the end. Color role ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To print text in red or green, use :code:`:red:\`text\`` and :code:`:green:\`text\``. Link roles ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The link roles are a group of roles defined by ``adi_links.py``. The ``validate_links`` global option is used to validate each link during build. These links are not managed, that means, only links from changed files are checked. You can run a build with it set to False, then touch the desired files to check the links of only these files. Git role ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ The Git role allows to create links to the Git repository with a shorter syntax. The role syntax is :code:`:git-repo:\`text \``, for example: * :code:`:git-hdl:\`main:docs/user_guide/docs_guidelines.rst\`` renders as :git-hdl:`main:docs/user_guide/docs_guidelines.rst`. * :code:`:git-hdl:\`Guidelines \`` renders as :git-hdl:`Guidelines `. When the branch field is not present, it will be filled with the current branch. It is recommended to not provide this field when it is a link to its own repository, because it is useful to auto-fill it for documentation releases (e.g. ``hdl_2023_r2``). A scenario where it is recommended to provide the branch is when linking others repositories. The text field is optional and will be filled with the full path. Finally, you can do :code:`:git-repo:\`/\`` for a link to the root of the repository with pretty naming, for example, :code:`:git-hdl:\`/\`` is rendered as :git-hdl:`/`. ADI role ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ The adi role creates links for a webpage to the Analog Devices Inc. website. The role syntax is :code:`:adi:\`text \``, for example, :code:`:adi:\`AD7175-2 \``. Since links are case insensitive, you can also reduce it to :code:`:adi:\`AD7175-2\``, when *webpage* is the same as *text* and will render as :adi:`AD7175-2`. Datasheet role ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ The datasheet role creates links for a datasheet in the Analog Devices Inc. website. The role syntax is :code:`:datasheet:\`part_id:anchor\``, for example, :code:`:datasheet:\`AD7984:[{"num"%3A51%2C"gen"%3A0}%2C{"name"%3A"XYZ"}%2C52%2C713%2C0]\`` is rendered as :datasheet:`AD7984:[{"num"%3A51%2C"gen"%3A0}%2C{"name"%3A"XYZ"}%2C52%2C713%2C0]`. The anchor is optional and is a link to a section of the PDF, and can be obtained by just copying the link in the table of contents. .. caution:: Since not all PDF readers support anchors, always provide the page and/or figure number! Dokuwiki role ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ The dokuwiki role creates links to the Analog Devices Inc. wiki website. The role syntax is :code:`:dokuwiki:\`text \``, for example, :code:`:dokuwiki:\`pulsar-adc-pmods \`` gets rendered as :dokuwiki:`pulsar-adc-pmods `. EngineerZone role ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ The ez role creates links to the Analog Devices Inc. EngineerZone support website. The role syntax is :code:`:ez:\`community\``, for example, :code:`:ez:\`fpga\`` gets rendered as :ez:`fpga`. For Linux Software Drivers, it is :code:`:ez:\`linux-software-drivers\``. For Microcontroller no-OS Drivers it is :code:`:ez:\`microcontroller-no-os-drivers\``. Vendor role ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ The vendor role creates links to the vendor's website. The role syntax is :code:`:vendor:\`text \``, for example, :code:`:xilinx:\`Zynq-7000 SoC Overview \`` gets rendered :xilinx:`Zynq-7000 SoC Overview `. The text parameter is optional, if absent, the file name will be used as the text, for example, :code:`:intel:\`content/www/us/en/docs/programmable/683780/22-4/general-purpose-i-o-overview.html\`` gets rendered :intel:`content/www/us/en/docs/programmable/683780/22-4/general-purpose-i-o-overview.html` (not very readable). Supported vendors are: ``xilinx`` (AMD Xilinx), ``intel`` (Intel Altera) and ``mw`` (MathWorks). HDL parameters directive ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The HDL parameters directive gets information parsed from IP-XACT (*component.xml*) library and generates a table with the IP parameters. .. note:: The IP-XACT files are generated by Vivado during the library build and not by the documentation tooling. The directive syntax is: .. code:: rst .. hdl-parameters:: :path: * - - For example: .. code:: rst .. hdl-parameters:: :path: library/spi_engine/spi_engine_interconnect * - DATA_WIDTH - Data width of the parallel SDI/SDO data interfaces. * - NUM_OF_SDI - Number of SDI lines on the physical SPI interface. Renders as: .. hdl-parameters:: :path: library/spi_engine/spi_engine_interconnect * - DATA_WIDTH - Data width of the parallel SDI/SDO data interfaces. * - NUM_OF_SDI - Number of SDI lines on the physical SPI interface. Descriptions in the directive have higher precedence than in the *component.xml* file. The ``:path:`` option is optional, and should **not** be included if the documentation file path matches the *component.xml* hierarchically. HDL interface directive ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The HDL interfaces directive gets information parsed from *component.xml* library and generates tables with the IP interfaces, both buses and ports. .. note:: The *component.xml* files are generated by Vivado during the library build and not by the documentation tooling. The directive syntax is: .. code:: rst .. hdl-interfaces:: :path: * - - For example: .. code:: rst .. hdl-interfaces:: :path: library/spi_engine/spi_engine_interconnect Descriptions in the directive have higher precedence than in the *component.xml* file. You can provide description to a port or a bus, but not for a bus port. The ``:path:`` option is optional, and should **not** be included if the documentation file path matches the *component.xml* hierarchically. HDL regmap directive ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The HDL regmap directive gets information from *docs/regmap/adi_regmap_\*.txt* files and generates tables with the register maps. The directive syntax is: .. code:: rst .. hdl-regmap:: :name: :no-type-info: For example: .. code:: rst .. hdl-regmap:: :name: DMAC .. note:: The register map name is the title-tool, the value above ``ENDTITLE`` in the source file. This directive does not support content for descriptions, since the source file already have proper descriptions. The ``:name:`` option is **required**, because the title tool does not match the IP name and one single *docs/regmap/adi_regmap_\*.txt* file can have more than one register map. The ``:no-type-info:`` option is optional, and should **not** be included if it is in the main IP documentation page. It appends an auxiliary table explaining the register access types. Collapsible directive ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The collapsible directive creates a collapsible/dropdown/"HTML details". The directive syntax is: .. code:: rst .. collapsible::