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>

.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

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

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

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

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

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

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