From ed0f496d56197b6ea68cf528f98d5cd370d32a33 Mon Sep 17 00:00:00 2001 From: Jorge Marques <2892061+gastmaier@users.noreply.github.com> Date: Wed, 15 Nov 2023 12:13:26 -0300 Subject: [PATCH] docs: flatten images paths, toctree and images guidelines (#1222) Recommend storing images like any other artifact: in a hierarchical manner, without "images" subfolders. This is intended to avoid dangling artifacts when projects are moved, renamed, or deleted. Recommend overwriting the page title with a shorter title in the toctree, so the navigation bar doesn't overflow or get too cluttered. Add acostina to CODEOWNERS Signed-off-by: Jorge Marques --- .github/CODEOWNERS | 2 +- docs/index.rst | 6 +- .../ad7616_sdz/ad7616_parallel_hdl.svg | 0 .../ad7616_sdz/ad7616_serial_hdl.svg | 0 docs/projects/ad7616_sdz/index.rst | 4 +- .../ad9081_fmca_ebz/ad9081_204b_M4L8.svg | 0 .../ad9081_fmca_ebz/ad9081_204b_M8L4.svg | 0 .../ad9081_fmca_ebz/ad9081_204c_M2L8.svg | 0 .../ad9081_clock_scheme_vcu118.svg | 0 .../ad9081_clock_scheme_zcu102.svg | 0 docs/projects/ad9081_fmca_ebz/index.rst | 10 ++-- .../ad9783_zcu102_block_diagram.svg | 0 .../ad9783_ebz/ad9783_zcu102_spi_pmod.svg | 0 docs/projects/ad9783_ebz/index.rst | 11 ++-- docs/projects/template/index.rst | 2 +- docs/user_guide/docs_guidelines.rst | 59 ++++++++++++++++++- 16 files changed, 75 insertions(+), 19 deletions(-) rename docs/projects/{images => }/ad7616_sdz/ad7616_parallel_hdl.svg (100%) rename docs/projects/{images => }/ad7616_sdz/ad7616_serial_hdl.svg (100%) rename docs/projects/{images => }/ad9081_fmca_ebz/ad9081_204b_M4L8.svg (100%) rename docs/projects/{images => }/ad9081_fmca_ebz/ad9081_204b_M8L4.svg (100%) rename docs/projects/{images => }/ad9081_fmca_ebz/ad9081_204c_M2L8.svg (100%) rename docs/projects/{images => }/ad9081_fmca_ebz/ad9081_clock_scheme_vcu118.svg (100%) rename docs/projects/{images => }/ad9081_fmca_ebz/ad9081_clock_scheme_zcu102.svg (100%) rename docs/projects/{images => }/ad9783_ebz/ad9783_zcu102_block_diagram.svg (100%) rename docs/projects/{images => }/ad9783_ebz/ad9783_zcu102_spi_pmod.svg (100%) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 39a287b1b..8f7144f4d 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -217,4 +217,4 @@ /library/jesd204/ ionut.podgoreanu@analog.com adrian.costina@analog.com # Code owners for docs -/docs/ iulia.moldovan@analog.com jorge.marques@analog.com stanca.pop@analog.com laez.barbosa@analog.com +/docs/ iulia.moldovan@analog.com jorge.marques@analog.com stanca.pop@analog.com laez.barbosa@analog.com adrian.costina@analog.com diff --git a/docs/index.rst b/docs/index.rst index 27d9ee3b8..b0bda7390 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,9 +20,9 @@ HDL Reference Designs :caption: Projects :hidden: - projects/ad7616_sdz/index - projects/ad9081_fmca_ebz/index - projects/ad9783_ebz/index + AD7616-SDZ + AD9081-FMCA-EBZ/AD9082-FMCA-EBZ + AD9783-EBZ .. role:: red .. role:: green diff --git a/docs/projects/images/ad7616_sdz/ad7616_parallel_hdl.svg b/docs/projects/ad7616_sdz/ad7616_parallel_hdl.svg similarity index 100% rename from docs/projects/images/ad7616_sdz/ad7616_parallel_hdl.svg rename to docs/projects/ad7616_sdz/ad7616_parallel_hdl.svg diff --git a/docs/projects/images/ad7616_sdz/ad7616_serial_hdl.svg b/docs/projects/ad7616_sdz/ad7616_serial_hdl.svg similarity index 100% rename from docs/projects/images/ad7616_sdz/ad7616_serial_hdl.svg rename to docs/projects/ad7616_sdz/ad7616_serial_hdl.svg diff --git a/docs/projects/ad7616_sdz/index.rst b/docs/projects/ad7616_sdz/index.rst index c49d40e02..0014844aa 100644 --- a/docs/projects/ad7616_sdz/index.rst +++ b/docs/projects/ad7616_sdz/index.rst @@ -60,7 +60,7 @@ Block diagram AD7616_SDZ serial interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. image:: ../images/ad7616_sdz/ad7616_serial_hdl.svg +.. image:: ad7616_serial_hdl.svg :width: 800 :align: center :alt: AD7616_SDZ using the serial interface block diagram @@ -68,7 +68,7 @@ AD7616_SDZ serial interface AD7616_SDZ parallel interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. image:: ../images/ad7616_sdz/ad7616_parallel_hdl.svg +.. image:: ad7616_parallel_hdl.svg :width: 800 :align: center :alt: AD7616_SDZ using the parallel interface block diagram diff --git a/docs/projects/images/ad9081_fmca_ebz/ad9081_204b_M4L8.svg b/docs/projects/ad9081_fmca_ebz/ad9081_204b_M4L8.svg similarity index 100% rename from docs/projects/images/ad9081_fmca_ebz/ad9081_204b_M4L8.svg rename to docs/projects/ad9081_fmca_ebz/ad9081_204b_M4L8.svg diff --git a/docs/projects/images/ad9081_fmca_ebz/ad9081_204b_M8L4.svg b/docs/projects/ad9081_fmca_ebz/ad9081_204b_M8L4.svg similarity index 100% rename from docs/projects/images/ad9081_fmca_ebz/ad9081_204b_M8L4.svg rename to docs/projects/ad9081_fmca_ebz/ad9081_204b_M8L4.svg diff --git a/docs/projects/images/ad9081_fmca_ebz/ad9081_204c_M2L8.svg b/docs/projects/ad9081_fmca_ebz/ad9081_204c_M2L8.svg similarity index 100% rename from docs/projects/images/ad9081_fmca_ebz/ad9081_204c_M2L8.svg rename to docs/projects/ad9081_fmca_ebz/ad9081_204c_M2L8.svg diff --git a/docs/projects/images/ad9081_fmca_ebz/ad9081_clock_scheme_vcu118.svg b/docs/projects/ad9081_fmca_ebz/ad9081_clock_scheme_vcu118.svg similarity index 100% rename from docs/projects/images/ad9081_fmca_ebz/ad9081_clock_scheme_vcu118.svg rename to docs/projects/ad9081_fmca_ebz/ad9081_clock_scheme_vcu118.svg diff --git a/docs/projects/images/ad9081_fmca_ebz/ad9081_clock_scheme_zcu102.svg b/docs/projects/ad9081_fmca_ebz/ad9081_clock_scheme_zcu102.svg similarity index 100% rename from docs/projects/images/ad9081_fmca_ebz/ad9081_clock_scheme_zcu102.svg rename to docs/projects/ad9081_fmca_ebz/ad9081_clock_scheme_zcu102.svg diff --git a/docs/projects/ad9081_fmca_ebz/index.rst b/docs/projects/ad9081_fmca_ebz/index.rst index 4e7d353d3..bacc2b91c 100644 --- a/docs/projects/ad9081_fmca_ebz/index.rst +++ b/docs/projects/ad9081_fmca_ebz/index.rst @@ -110,7 +110,7 @@ Block diagram Example block design for Single link; M=8; L=4 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. image:: ../images/ad9081_fmca_ebz/ad9081_204b_M8L4.svg +.. image:: ad9081_204b_M8L4.svg :width: 800 :align: center :alt: AD9081-FMCA-EBZ JESD204B M=8 L=4 block diagram @@ -140,7 +140,7 @@ The Tx links (DAC Path) operate with the following parameters: Example block design for Single link; M=4; L=8 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. image:: ../images/ad9081_fmca_ebz/ad9081_204b_M4L8.svg +.. image:: ad9081_204b_M4L8.svg :width: 800 :align: center :alt: AD9081-FMCA-EBZ JESD204B M=4 L=8 block diagram @@ -176,7 +176,7 @@ Example block design for Single link; M=2; L=8; JESD204C In 2019_R2 release, the AMD JESD Physical layer IP Core is used, however in newer versions it is replaced with ADI's util_adxcvr IP core. -.. image:: ../images/ad9081_fmca_ebz/ad9081_204c_M2L8.svg +.. image:: ad9081_204c_M2L8.svg :width: 800 :align: center :alt: AD9081-FMCA-EBZ JESD204C M=2 L=8 block diagram @@ -281,7 +281,7 @@ The clock sources depend on the carrier that is used: :xilinx:`ZCU102` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. image:: ../images/ad9081_fmca_ebz/ad9081_clock_scheme_zcu102.svg +.. image:: ad9081_clock_scheme_zcu102.svg :width: 800 :align: center :alt: AD9081-FMCA-EBZ ZCU102 clock scheme @@ -289,7 +289,7 @@ The clock sources depend on the carrier that is used: :xilinx:`VCU118` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. image:: ../images/ad9081_fmca_ebz/ad9081_clock_scheme_vcu118.svg +.. image:: ad9081_clock_scheme_vcu118.svg :width: 800 :align: center :alt: AD9081-FMCA-EBZ VCU118 clock scheme diff --git a/docs/projects/images/ad9783_ebz/ad9783_zcu102_block_diagram.svg b/docs/projects/ad9783_ebz/ad9783_zcu102_block_diagram.svg similarity index 100% rename from docs/projects/images/ad9783_ebz/ad9783_zcu102_block_diagram.svg rename to docs/projects/ad9783_ebz/ad9783_zcu102_block_diagram.svg diff --git a/docs/projects/images/ad9783_ebz/ad9783_zcu102_spi_pmod.svg b/docs/projects/ad9783_ebz/ad9783_zcu102_spi_pmod.svg similarity index 100% rename from docs/projects/images/ad9783_ebz/ad9783_zcu102_spi_pmod.svg rename to docs/projects/ad9783_ebz/ad9783_zcu102_spi_pmod.svg diff --git a/docs/projects/ad9783_ebz/index.rst b/docs/projects/ad9783_ebz/index.rst index dab92f367..4e84face6 100644 --- a/docs/projects/ad9783_ebz/index.rst +++ b/docs/projects/ad9783_ebz/index.rst @@ -42,7 +42,7 @@ Block diagram The data path and clock domains are depicted in the below diagram: -.. image:: ../images/ad9783_ebz/ad9783_zcu102_block_diagram.svg +.. image:: ad9783_zcu102_block_diagram.svg :width: 800 :align: center :alt: AD9783-EBZ/ZCU102 block diagram @@ -127,7 +127,10 @@ Software considerations The SPI communication is changed because of hardware modifications, so the connection looks like this: -|ad9783_zcu102_spi_pmod.svg| +.. image:: ad9783_zcu102_spi_pmod.svg + :width: 600 + :align: center + :alt: AD9783-EBZ/ZCU102 SPI Pmod connection Resources ------------------------------------------------------------------------------- @@ -203,7 +206,3 @@ Software related .. include:: ../common/support.rst -.. |ad9783_zcu102_spi_pmod.svg| image:: ../images/ad9783_ebz/ad9783_zcu102_spi_pmod.svg - :width: 600 - :align: top - :alt: AD9783-EBZ/ZCU102 SPI Pmod connection diff --git a/docs/projects/template/index.rst b/docs/projects/template/index.rst index 02002ca87..c473d5ea9 100644 --- a/docs/projects/template/index.rst +++ b/docs/projects/template/index.rst @@ -95,7 +95,7 @@ the below diagram: If the project has multiple ways of configuration, then make subsections to this section and show the default configuration and some other popular modes. -.. image:: ../images/ad9783_ebz/ad9783_zcu102_block_diagram.svg +.. image:: ../ad9783_ebz/ad9783_zcu102_block_diagram.svg :width: 800 :align: center :alt: AD9783-EBZ/ZCU102 block diagram diff --git a/docs/user_guide/docs_guidelines.rst b/docs/user_guide/docs_guidelines.rst index 07ffd7718..e11003572 100644 --- a/docs/user_guide/docs_guidelines.rst +++ b/docs/user_guide/docs_guidelines.rst @@ -27,9 +27,50 @@ 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 +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 -------------------------------------------------------------------------------- @@ -125,6 +166,22 @@ 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~