Merge pull request f4pga#2413 from antmicro/umarcor/docs-extlinks-int…

…ersphinx

docs: use extensions ExtLinks and InterSphinx

.readthedocs.yml

@@ -23,7 +23,7 @@ version: 2
 
 sphinx:
   configuration: docs/conf.py
-  fail_on_warning: true
+  fail_on_warning: false
 
 python:
   version: "3.7"

docs/conf.py

@@ -25,6 +25,8 @@
 
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.extlinks',
+    'sphinx.ext.intersphinx',
     'sphinxcontrib.images',
 ]
 
@@ -96,3 +98,29 @@
         'f4pga-arch-defs', 'One line description of project.', 'Miscellaneous'
     ),
 ]
+
+# -- Sphinx.Ext.InterSphinx ------------------------------------------------------------------------
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3.6/', None),
+    'f4pga': ('https://f4pga.readthedocs.io/en/latest/', None),
+    'examples': ('https://f4pga-examples.readthedocs.io/en/latest', None),
+    'constraints': ('https://hdl.github.io/constraints/', None),
+}
+
+# -- Sphinx.Ext.ExtLinks ---------------------------------------------------------------------------
+
+extlinks = {
+    'wikipedia': ('https://en.wikipedia.org/wiki/%s', 'wikipedia:'),
+    'gh': ('https://github.com/%s', 'gh:'),
+    'ghsharp': ('https://github.com/SymbiFlow/f4pga-arch-defs/issues/%s', '#'),
+    'ghissue':
+        ('https://github.com/SymbiFlow/f4pga-arch-defs/issues/%s', 'issue #'),
+    'ghpull':
+        (
+            'https://github.com/SymbiFlow/f4pga-arch-defs/pull/%s',
+            'pull request #'
+        ),
+    'ghsrc':
+        ('https://github.com/SymbiFlow/f4pga-arch-defs/blob/master/%s', '')
+}

docs/development/structure.rst

@@ -4,70 +4,84 @@ Structure
 Directories
 -----------
 
-* `XXX/device/` - Full architecture definitions of a given device for
-  [Verilog To Routing](https://verilogtorouting.org/)
-
-  * `XXX/device/YYYY-virt` - Verilog to Routing architecture definitions
-    generally are not able to able to generate the **exact** model of many
-    FPGA routing interconnects, but this is a pretty close.
-* `XXX/primitives/` - The primitives that make up the architecture. These
-  are generally used inside the tiles.
-* `XXX/tiles/` - The tiles found in the architecture.
-* `XXX/tests/` - Tests for making sure the architecture specific features
-  works with VPR.
-* [`vpr`](vpr) - Common defines used by multiple architectures.
+* ``XXX/device/`` - Full architecture definitions of a given device for `Verilog To Routing <https://verilogtorouting.org/>`__
+
+  * ``XXX/device/YYYY-virt`` - Verilog to Routing architecture definitions generally are not able to able to generate
+    the **exact** model of many FPGA routing interconnects, but this is a pretty close.
+
+* ``XXX/primitives/`` - The primitives that make up the architecture.
+  These are generally used inside the tiles.
+* ``XXX/tiles/`` - The tiles found in the architecture.
+* ``XXX/tests/`` - Tests for making sure the architecture specific features works with VPR.
+* :ghsrc:`vpr` - Common defines used by multiple architectures.
 
 Files
 -----
 
-* `pb_type.xml` - The Verilog to Routing
-  [Complex Block](https://docs.verilogtorouting.org/en/latest/arch/reference/#complex-blocks)
+* `pb_type.xml` - The Verilog to Routing `Complex Block <https://docs.verilogtorouting.org/en/latest/arch/reference/#complex-blocks>`__
   defintinition.
 
-  * Inside `primitives` directory they should be intermediate or primitive
-    `<pb_type>` and thus allow setting the `num_pb` attribute.
-  * Inside `tiles` directory they should be top level `<pb_type>` and thus have,
+  * Inside ``primitives`` directory they should be intermediate or primitive ``<pb_type>`` and thus allow setting the
+    ``num_pb`` attribute.
+
+  * Inside ``tiles`` directory they should be top level ``<pb_type>`` and thus have,
 
-    - `capacity` (if a pin type),
-    - `width` & `height` (and maybe `area`)
-* `model.xml` - The Verilog to Routing
-  [Recognized BLIF Models](https://docs.verilogtorouting.org/en/latest/arch/reference/#recognized-blif-models-models)
+    * ``capacity`` (if a pin type),
+    * ``width`` & ``height`` (and maybe ``area``)
+
+* ``model.xml`` - The Verilog to Routing `Recognized BLIF Models <https://docs.verilogtorouting.org/en/latest/arch/reference/#recognized-blif-models-models>`__
   defintinition.
-* `sim.v` - A Verilog definition of the object. It should;
-
-  - [ ] Match the definition in `model.xml` (should be one `module` in
-    `sim.v` for every `model` in `model.xml`)
-  - [ ] Include a `ifndef BLACKBOX` section which actually defines how the
-    Verilog works.
-* `macro.v` - A Verilog definition of the object which a user might
-  instantiate in their own code when specifying a primitive. This should match
-  the definition provided by a manufacturer. Examples would be the definitions
-  in;
-
-  - [Lattice iCE Technology Library](http://www.latticesemi.com/~/media/LatticeSemi/Documents/TechnicalBriefs/SBTICETechnologyLibrary201504.pdf)
-  - [UG953: Vivado Design Suite 7 Series FPGA and Zynq-7000 All Programmable SoC Libraries Guide](https://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_3/ug953-vivado-7series-libraries.pdf)
+
+* ``sim.v`` - A Verilog definition of the object.
+  It should:
+
+  - [ ] Match the definition in ``model.xml`` (should be one ``module`` in ``sim.v`` for every ``model`` in ``model.xml``)
+
+  - [ ] Include a ``ifndef BLACKBOX`` section which actually defines how the Verilog works.
+
+* ``macro.v`` - A Verilog definition of the object which a user might instantiate in their own code when specifying a
+  primitive.
+  This should match the definition provided by a manufacturer.
+  Examples would be the definitions in:
+
+  - `Lattice iCE Technology Library <http://www.latticesemi.com/~/media/LatticeSemi/Documents/TechnicalBriefs/SBTICETechnologyLibrary201504.pdf>`__
+  - `UG953: Vivado Design Suite 7 Series FPGA and Zynq-7000 All Programmable SoC Libraries Guide <https://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_3/ug953-vivado-7series-libraries.pdf>`__
 
 Names
 -----
 
-* ``BLK_MB-block_1_name-block_2_name`` - ``BLOCK`` which is a "**m**\ ega **b**\ lock". A "mega block" is a top level block which is made up of other blocks.
-* ``BLK_XX-name``       - ``BLOCK`` which is the hierarchy. Maps to ``BLK_SI`` -> ``SITE`` and ``BLK_TI`` -> ``TILE`` in Xilinx terminology.
-* ``BLK_IG-name``       - ``BLOCK`` which is ignored. They don't appear in the output hierarchy and are normally used when something is needed in the description which doesn't match actual architecture.
-* ``BEL_RX-mux_name``   - ``BEL`` which is a **r**\ outing mu\ **x**. Routing muxes are statically configured at PnR time.
+* ``BLK_MB-block_1_name-block_2_name`` - ``BLOCK`` which is a "**m**\ ega **b**\ lock".
+  A "mega block" is a top level block which is made up of other blocks.
+
+* ``BLK_XX-name``       - ``BLOCK`` which is the hierarchy.
+  Maps to ``BLK_SI`` -> ``SITE`` and ``BLK_TI`` -> ``TILE`` in Xilinx terminology.
+
+* ``BLK_IG-name``       - ``BLOCK`` which is ignored.
+  They don't appear in the output hierarchy and are normally used when something is needed in the description which
+  doesn't match actual architecture.
+
+* ``BEL_RX-mux_name``   - ``BEL`` which is a **r**\ outing mu\ **x**.
+  Routing muxes are statically configured at PnR time.
+
 * ``BEL_MX-mux_name``   - ``BEL`` which is a **m**\ u\ **x** .
+
 * ``BEL_LT-lut_name``   - ``BEL`` which is a **l**\ ook up **t**\ able.
+
 * ``BEL_MM-mem_name``   - ``BEL`` which is a **m**\ e**m**\ ory.
+
 * ``BEL_FF-ff_name``    - ``BEL`` which is a **f**\ lip **f**\ lop (``FF``).
+
 * ``BEL_LL-latch_name`` - ``BEL`` which is a **l**\ atch (``LL``).
+
 * ``BEL_BB-name``       - ``BEL`` which is a **b**\ lack **b**\ ox (``BB``).
+
 * ``PAD_IN-name``       - A signal input location.
+
 * ``PAD_OT-name``       - A signal output location.
 
 Notes
 -----
 
-* Unless there is a good reason otherwise, all muxes should be generated via
-  [`mux_gen.py`](utils/mux_gen.py)
+* Unless there is a good reason otherwise, all muxes should be generated via `mux_gen.py <utils/mux_gen.py>`__.
 
-* DRY (Don't repeat yourself) - Uses
-  [XML XIncludes](https://en.wikipedia.org/wiki/XInclude) to reuse stuff!
+* DRY (Don't repeat yourself) - Uses :wikipedia:`XML XIncludes <XInclude>` to reuse stuff!

docs/getting-started.rst

@@ -4,7 +4,7 @@ Getting Started with F4PGA Toolchain development
 
 .. warning::
    This documentation explains the first steps in the development of the toolchain itself.
-   If you are looking for the **user documentation**, please look at https://f4pga-examples.readthedocs.io/en/latest/ instead.
+   If you are looking for the **user documentation**, please look at :doc:`examples:index` instead.
 
 This section provides an introduction on how to get started with the development of the F4PGA toolchain.
 In order to generate a bitstream (or any intermediate file format), you can use one of the toolchain tests.
@@ -43,11 +43,11 @@ Each architecture has its own toolchain backend that will be called during build
 (See `Project X-Ray <https://prjxray.readthedocs.io/en/latest/>`_
 and `Project Trellis <https://prjtrellis.readthedocs.io/en/latest/>`_ for more information)
 
-For development purposes a set of test designs are included for each supported architecture. In order to perform a build
-of a test design with the ``Make`` build system enter the appropriate test build directory specific to your target architecture
-and invoke desired make target.
-Assuming that you would like to generate the bitstream ``.bit`` file with the counter example for the Arty board, which uses Xilinx Artix-7 FPGA,
-you will execute the following:
+For development purposes a set of test designs are included for each supported architecture.
+In order to perform a build of a test design with the ``Make`` build system enter the appropriate test build directory
+specific to your target architecture and invoke desired make target.
+Assuming that you would like to generate the bitstream ``.bit`` file with the counter example for the Arty board, which
+uses Xilinx Artix-7 FPGA, you will execute the following:
 
 .. code-block:: bash
 
@@ -97,27 +97,26 @@ or for ``Ninja``:
 .. note::
     Loading the bitstream into an FPGA can be done outside of the F4PGA.
     There are multiple tools for loading bitstreams into FPGA development boards.
-    Typically, each tool supports a specific target family or the lines
-    of products of a vendor. Some of the most known are listed in `hdl/constraints/prog <https://github.com/hdl/constraints/tree/main/prog>`_
+    Typically, each tool supports a specific target family or the lines of products of a vendor.
+    Some of the most known are listed in :ref:`hdl/constraints: Programming and debugging <constraints:ProgDebug>`.
 
 OpenFPGALoader
 --------------
 
-OpenFPGALoader is an universal utility for programming the FPGA devices that is
-a great alternative to OpenOCD. It supports many different boards with FPGAs
-based on the architectures including xc7, ECP5, iCE40 and many more. It can utilize
-a variety of the programming adapters based on JTAG, DAP interface, ORBTrace,
-DFU and FTDI chips.
+OpenFPGALoader is an universal utility for programming the FPGA devices that is a great alternative to OpenOCD.
+It supports many different boards with FPGAs based on the architectures including xc7, ECP5, iCE40 and many more.
+It can utilize a variety of the programming adapters based on JTAG, DAP interface, ORBTrace, DFU and FTDI chips.
 
 Installing OpenFPGALoader
 *************************
 
-OpenFPGALoader is available in several packaging solutions. It can be installed
-with distribution specific package managers on Arch Linux and Fedora.
-There are also prebuilt packages available in `conda <https://anaconda.org/litex-hub/openfpgaloader>`_
-or packages in tool `repository <https://github.com/trabucayre/openFPGALoader/releases>`_.
-OpenFPGALoader can also be built from sources. For installation guidelines
-using both prebuilt packages and building from source please refer to instructions in `readme <https://github.com/trabucayre/openFPGALoader/blob/master/INSTALL.md>`_.
+OpenFPGALoader is available in several packaging solutions.
+It can be installed with distribution specific package managers on Arch Linux and Fedora.
+There are also prebuilt packages available in `conda <https://anaconda.org/litex-hub/openfpgaloader>`__
+or packages in tool :gh:`repository <trabucayre/openFPGALoader/releases>`.
+OpenFPGALoader can also be built from sources.
+For installation guidelines using both prebuilt packages and building from source please refer to instructions in
+:gh:`readme <trabucayre/openFPGALoader/blob/master/INSTALL.md>`.
 
 Usage
 *****
@@ -126,18 +125,17 @@ For programming the FPGA use one of these commands:
 
 .. code-block:: bash
 
-        openFPGALoader -b <board> <bitstream>           # (e.g. arty)
-        openFPGALoader -c <cable> <bitstream>           # (e.g. digilent)
-        openFPGALoader -d <device> <bitstream>          # (e.g. /dev/ttyUSB0)
+    openFPGALoader -b <board> <bitstream>           # (e.g. arty)
+    openFPGALoader -c <cable> <bitstream>           # (e.g. digilent)
+    openFPGALoader -d <device> <bitstream>          # (e.g. /dev/ttyUSB0)
 
 You can also list the supported boards, cables and fpgas:
 
 .. code-block:: bash
 
-        openFPGALoader --list-boards
-        openFPGALoader --list-cables
-        openFPGALoader --list-fpga
-
-If you encounter any issues, please refer to the `OpenFPGALoader README <https://github.com/trabucayre/openFPGALoader#readme>`_
-as it provides more useful information on the usage of the tool.
+    openFPGALoader --list-boards
+    openFPGALoader --list-cables
+    openFPGALoader --list-fpga
 
+If you encounter any issues, please refer to the :gh:`OpenFPGALoader README <trabucayre/openFPGALoader#readme>` as it
+provides more useful information on the usage of the tool.