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