Merge pull request #258 from antmicro/umarcor/docs/structure

docs: use multiple toctrees with different captions

.github/scripts/build-examples.sh

@@ -55,7 +55,7 @@ fi
 # activate conda and enter example dir
 activate_env="docs/building-examples.rst:export-install-dir,fpga-fam-$fpga_family,conda-prep-env-$fpga_family,conda-act-env"
 snippets="${activate_env},enter-dir-$fpga_family"
-additionalDesigns="${activate_env},enter-dir-$fpga_family,additional_examples"
+additionalDesigns="${activate_env},enter-dir-$fpga_family"
 
 
 # Xilinx 7-Series examples
@@ -80,7 +80,7 @@ if [ "$fpga_family" = "xc7" ]; then
 
             #Additional examples:
             "button_controller")
-                snippets="${additionalDesigns} xc7/additional_examples/button_controller/README.rst:example-debouncer-basys3"
+                snippets="${additionalDesigns} xc7/additional_examples/button_controller/README.rst:additional-examples,example-debouncer-basys3"
                 ;;
             "pulse_width_led")
                 snippets="${snippets} xc7/pulse_width_led/README.rst:example-pulse-arty-35t"

.github/scripts/install-toolchain.sh

@@ -45,4 +45,4 @@ fi
 fpga_family=$1
 os=$2
 
-tuttest_exec docs/getting-f4pga.rst:install-reqs-$os,wget-conda,conda-install-dir,fpga-fam-$fpga_family,conda-setup,download-arch-def-$fpga_family
+tuttest_exec docs/getting.rst:install-reqs-$os,wget-conda,conda-install-dir,fpga-fam-$fpga_family,conda-setup,download-arch-def-$fpga_family

docs/basys3.rst

@@ -0,0 +1,9 @@
+Additional Basys3 Examples
+==========================
+
+You can find several other exciting designs for the basys3 board in the additional_examples directory:
+
+.. code-block:: bash
+   :name: additional_examples
+
+   cd additional_examples

docs/building-examples.rst

@@ -1,5 +1,7 @@
+.. _Building-Examples:
+
 Building example designs
-========================
+########################
 
 Before building any example, set the installation directory to match what you
 set it to earlier, for example:
@@ -74,7 +76,7 @@ Finally, enter your working Conda environment:
 
 
 Xilinx 7-Series
----------------
+===============
 
 Enter the directory that contains examples for Xilinx 7-Series FPGAs:
 
@@ -99,24 +101,11 @@ Enter the directory that contains examples for Xilinx 7-Series FPGAs:
    :file: templates/example.jinja
 
 .. jinja:: xc7_pulse_width_led
-   :file: templates/example.jinja 
+   :file: templates/example.jinja
-
-
-
-Additional Examples
--------------------
-
-In addition to the designs we have gone over here, you can also find several other exciting designs
-for the basys3 board in the additional_examples directory:
-
-.. code-block:: bash
-   :name: additional_examples
-
-   cd additional_examples
 
 
 QuickLogic EOS S3
------------------
+=================
 
 Enter the directory that contains examples for QuickLogic EOS S3:
 

docs/customizing-makefiles.rst

@@ -1,13 +1,12 @@
 Customizing the Makefiles
-==========================
+=========================
 
-A powerful tool in creating your own designs is understanding how to generate your own Makefile to
+A powerful tool in creating your own designs is understanding how to generate your own Makefile to compile projects.
-compile projects. This tutorial walks you through how to do that.
+This tutorial walks you through how to do that.
 
-If you would like to use methods other than a Makefile to build and compile your designs
+If you would like to use methods other than a Makefile to build and compile your designs (such as python or bash
-(such as python or bash scripts) or if you would like to learn more about the various F4PGA
+scripts) or if you would like to learn more about the various F4PGA commands used by the common Makefile to build and
-commands used by the common Makefile to build and compile designs take a look at the
+compile designs take a look at the :ref:`Understanding` page.
-`Understanding Toolchain Commands <understanding-commands.html>`_ page.
 
 Example
 -------
@@ -107,7 +106,7 @@ your design. The general syntax depends on whether you are using XDC files or a
 
 
 A Note on the example designs use of ifeq/else ifeq blocks
--------------------------------------------------------------
+----------------------------------------------------------
 
 If you look at the Makefiles from the example designs within F4PGA
 (i.e. counter test, Picosoc, etc.), you will find an ifeq else ifeq block. The following snippet

docs/getting.rst

@@ -1,11 +1,13 @@
+.. _Getting:
+
 Getting F4PGA
-=============
+#############
 
 This section describes how to install F4PGA and set up a fully working
 environment to later build example designs.
 
 Prerequisites
--------------
+=============
 
 To be able to follow through this tutorial, install the following software:
 
@@ -52,7 +54,7 @@ Next, clone the F4PGA examples repository and enter it:
    cd f4pga-examples
 
 Toolchain installation
-----------------------
+======================
 
 Now we are able to install the F4PGA toolchain. This procedure is divided
 into three steps:
@@ -62,7 +64,7 @@ into three steps:
 - downloading the architecture definitions and installing the toolchain.
 
 Conda
-~~~~~
+-----
 
 Download Conda installer script into the f4pga-examples directory:
 
@@ -84,8 +86,8 @@ and so you will need to add some ``sudo`` commands to the instructions below.
 
    export INSTALL_DIR=~/opt/f4pga
 
-Toolchain
+Setup and download assets
-~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Select your target FPGA family:
 
@@ -139,11 +141,9 @@ Download architecture definitions:
 
 If the above commands exited without errors, you have successfully installed and configured your working environment.
 
-Build Example Designs
+.. IMPORTANT::
----------------------
+  With the toolchain installed, you are ready to build the example designs!
+  Examples are provided in separated directories:
 
-With the toolchain installed, you can build the example designs.
+  * Subdir :ghsrc:`xc7` for the Artix-7 devices
-The example designs are provided in separate directories:
+  * Subdir :ghsrc:`eos-s3` for the EOS S3 devices
-
-* ``xc7`` directory for the Artix-7 devices
-* ``eos-s3`` directory for the EOS S3 devices

docs/index.rst

@@ -10,13 +10,12 @@ It currently focuses on the following FPGA families:
 
 Follow this guide to:
 
-- :doc:`install F4PGA <getting-f4pga>` and all of its dependencies,
+- :doc:`install F4PGA <getting>` and all of its dependencies,
 - :doc:`build <building-examples>` and :doc:`upload <running-examples>`
   example designs onto the devboard of your choice.
 - compile and run :doc:`your own designs<personal-designs>` using the F4PGA toolchain.
 - :doc:`customize the Makefile<customizing-makefiles>` for your own designs.
-- gain valuable information about `Understanding Toolchain Commands in F4PGA <understanding-commands.html>`_
+- gain valuable information about :doc:`Understanding Toolchain Commands in F4PGA <understanding>`.
-
 
 About F4PGA
 -----------
@@ -30,13 +29,24 @@ currently targeting chips from multiple vendors, e.g.:
 - QuickLogic EOS S3
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Sections
 
-   getting-f4pga
+   getting
+   understanding
+
+.. toctree::
+   :caption: Example designs
+
    building-examples
    running-examples
+
+.. toctree::
+   :caption: Custom designs
+
    personal-designs
    customizing-makefiles
-   understanding-commands
+
+.. toctree::
+   :caption: Additional example designs
+
    project-f
+   basys3

docs/personal-designs.rst

@@ -1,58 +1,59 @@
-Building Custom Designs
+.. _Building-Custom-Designs:
-========================
 
-This section describes how to compile and download your own designs to an FPGA using only 
+Building Custom Designs
+=======================
+
+This section describes how to compile and download your own designs to an FPGA using only
 the F4PGA toolchain.
 
-Before building any examples, you will need to first install the toolchain. To do this, follow the 
+Before building any examples, you will need to first install the toolchain. To do this, follow the steps in :ref:`Getting`.
-steps in `Getting F4PGA <getting-f4pga.html>`_. After you have downloaded the toolchain, 
+After you have downloaded the toolchain, follow the steps in :ref:`Building-Examples` by seting the installation
-follow the steps in `Building Examples <building-examples.html>`_ by seting the installation 
+directory to match what you set it to earlier, assigning the path and source for your conda environment, and activating
-directory to match what you set it to earlier, assigning the path and source for 
+your env.
-your conda environment, and activating your env.
 
-Preparing Your Design 
+Preparing Your Design
-----------------------
+---------------------
 
 Building a design in F4PGA requires three parts: the HDL files for your design, a constraints
 file, and a Makefile. For simplicity, all three of these design files should be moved to a single
-directory. The location of the directory does not mater as long as the three design elements are all 
+directory. The location of the directory does not mater as long as the three design elements are all
 within it.
 
 HDL Files
-++++++++++
++++++++++
 
-F4PGA provides full support for Verilog. Some support for SystemVerilog HDL code is also 
+F4PGA provides full support for Verilog. Some support for SystemVerilog HDL code is also
-provided, although more complicated designs written in SystemVerilog may not build properly under 
+provided, although more complicated designs written in SystemVerilog may not build properly under
-Yosys. Use whichever method you prefer, and add your design files to the directory of choice. 
+Yosys. Use whichever method you prefer, and add your design files to the directory of choice.
-If you are using the provided Makefiles to build your design, the top level module in your HDL 
+If you are using the provided Makefiles to build your design, the top level module in your HDL
-code should be declared as ``module top (...``. Failure to do so will result in an error from 
+code should be declared as ``module top (...``. Failure to do so will result in an error from
-symbiflow_synth stating something similar to ``ERROR: Module 'top' not found!`` If you are using 
+symbiflow_synth stating something similar to ``ERROR: Module 'top' not found!`` If you are using
-your own makefiles or commands, you can specify your top level module name using the -t flag in 
+your own makefiles or commands, you can specify your top level module name using the -t flag in
-``symbiflow_synth``. 
+``symbiflow_synth``.
 
 Constraint File
-++++++++++++++++
++++++++++++++++
 
-The F4PGA toolchain supports both .XDC and .PCF+.SDC formats for constraints. 
+The F4PGA toolchain supports both .XDC and .PCF+.SDC formats for constraints.
-You can use XDC to define IOPAD, IOSETTINGS, and clock constraints. SDCs can be used to 
+You can use XDC to define IOPAD, IOSETTINGS, and clock constraints. SDCs can be used to
-define clock constraints and PCFs can be used to define IOPAD constraints only. Use whichever 
+define clock constraints and PCFs can be used to define IOPAD constraints only. Use whichever
 method you prefer and add your constraint file(s) to your design directory.
 
-Note that if you use an XDC file as your constraint and neglect to include your own SDC, the 
+Note that if you use an XDC file as your constraint and neglect to include your own SDC, the
 toolchain will automatically generate one to provide clock constraints to VTR.
 
 
 Makefile
-+++++++++
+++++++++
 
-Visit the `Customizing Makefiles <customizing-makefiles.html>`_ page to learn how to make a simple 
+Visit the `Customizing Makefiles <customizing-makefiles.html>`_ page to learn how to make a simple
 Makefile for your designs. After following the directions listed there return to this page to
 finish building your custom design.
 
-Building your personal projects 
+Building your personal projects
 -------------------------------
 
-Before you begin building your design, navigate to the directory where you have stored your 
+Before you begin building your design, navigate to the directory where you have stored your
 Makefile, HDL, and constraint files:
 
 .. code-block:: bash
@@ -60,7 +61,7 @@ Makefile, HDL, and constraint files:
 
    cd <path to your directory>
 
-Then, depending on your board type run: 
+Then, depending on your board type run:
 
 .. tabs::
 
@@ -91,7 +92,7 @@ Then, depending on your board type run:
          :name: example-counter-basys3-group
 
          TARGET="basys3" make -C .
-      
+
    .. group-tab:: Nexys Video
 
       .. code-block:: bash
@@ -100,12 +101,12 @@ Then, depending on your board type run:
          TARGET="nexys_video" make -C counter_test
 
    .. group-tab:: Zybo Z7
-   
+
       .. code-block:: bash
          :name: example-counter-zybo-group
 
          TARGET="zybo" make -C counter_test
-   
+
 
 If your design builds without error, the bitstream can be found in the following location:
 
@@ -113,7 +114,7 @@ If your design builds without error, the bitstream can be found in the following
 
    cd build/<board>
 
-Once you navigate to the directory containing the bitstream, use the following commands on the 
+Once you navigate to the directory containing the bitstream, use the following commands on the
 **Arty and Basys3** to upload the design to your board. Make sure to change ``top.bit`` to the
 name you used for your top level module:
 
@@ -123,20 +124,20 @@ name you used for your top level module:
 
 
 .. tip::
-    Many of the commands needed to build a project are run multiple times with little to no 
+    Many of the commands needed to build a project are run multiple times with little to no
-    variation. You might consider adding a few aliases or even a few bash functions to your 
+    variation. You might consider adding a few aliases or even a few bash functions to your
-    .bashrc file to save yourself some typing or repeated copy/paste. For example, instead of 
+    .bashrc file to save yourself some typing or repeated copy/paste. For example, instead of
-    using the somewhat cumbersome command used to upload the bitstream to Xilinx 7 series FPGA 
+    using the somewhat cumbersome command used to upload the bitstream to Xilinx 7 series FPGA
     every time, you could just add the following lines to your .bashrc file:
-    
+
     .. code-block:: bash
        :name: bash-functions
 
-        symbi_bit() { 
+        symbi_bit() {
         #Creates and downloads the bitstream to Xilinx 7 series FPGA:
         openocd -f <Your install directory>/xc7/conda/envs/xc7/share/openocd/scripts/board/digilent_arty.cfg -c "init; pld load 0 top.bit; exit"
        }
 
-    Now whenever you need to download a bitstream to the Xilinx-7 series you can simply type 
+    Now whenever you need to download a bitstream to the Xilinx-7 series you can simply type
     ``symbi_bit`` into the terminal and hit enter.
 

docs/understanding.rst

@@ -1,5 +1,7 @@
-Understanding Toolchain Commands
+.. _Understanding:
-=================================
+
+Understanding the flow
+======================
 
 This section provides valuable information on how each of the commands used to compile and build
 designs in F4PGA work. It is especially helpful for debugging or for using methods