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 <jorge.marques@analog.com>main
|
@ -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
|
||||
|
|
|
@ -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 <projects/ad7616_sdz/index>
|
||||
AD9081-FMCA-EBZ/AD9082-FMCA-EBZ <projects/ad9081_fmca_ebz/index>
|
||||
AD9783-EBZ <projects/ad9783_ebz/index>
|
||||
|
||||
.. role:: red
|
||||
.. role:: green
|
||||
|
|
Before Width: | Height: | Size: 99 KiB After Width: | Height: | Size: 99 KiB |
Before Width: | Height: | Size: 101 KiB After Width: | Height: | Size: 101 KiB |
|
@ -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
|
||||
|
|
Before Width: | Height: | Size: 175 KiB After Width: | Height: | Size: 175 KiB |
Before Width: | Height: | Size: 187 KiB After Width: | Height: | Size: 187 KiB |
Before Width: | Height: | Size: 170 KiB After Width: | Height: | Size: 170 KiB |
Before Width: | Height: | Size: 132 KiB After Width: | Height: | Size: 132 KiB |
Before Width: | Height: | Size: 114 KiB After Width: | Height: | Size: 114 KiB |
|
@ -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
|
||||
|
|
Before Width: | Height: | Size: 79 KiB After Width: | Height: | Size: 79 KiB |
Before Width: | Height: | Size: 36 KiB After Width: | Height: | Size: 36 KiB |
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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 <path/to/page>
|
||||
|
||||
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 <projects/ad7616_sdz/index>
|
||||
|
||||
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 <https://inkscape.org/>`_ 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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
|