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:
 
@@ -102,21 +104,8 @@ Enter the directory that contains examples for Xilinx 7-Series FPGAs:
    :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
-compile projects. This tutorial walks you through how to do that.
+A powerful tool in creating your own designs is understanding how to generate your own Makefile to compile projects.
+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
-(such as python or bash scripts) or if you would like to learn more about the various F4PGA
-commands used by the common Makefile to build and compile designs take a look at the
-`Understanding Toolchain Commands <understanding-commands.html>`_ page.
+If you would like to use methods other than a Makefile to build and compile your designs (such as python or bash
+scripts) or if you would like to learn more about the various F4PGA commands used by the common Makefile to build and
+compile designs take a look at the :ref:`Understanding` 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.
-The example designs are provided in separate directories:
-
-* ``xc7`` directory for the Artix-7 devices
-* ``eos-s3`` directory for the EOS S3 devices
+  * Subdir :ghsrc:`xc7` for the Artix-7 devices
+  * Subdir :ghsrc:`eos-s3` 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,17 +1,18 @@
+.. _Building-Custom-Designs:
+
 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 
-steps in `Getting F4PGA <getting-f4pga.html>`_. After you have downloaded the toolchain, 
-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 your env.
+Before building any examples, you will need to first install the toolchain. To do this, follow the steps in :ref:`Getting`.
+After you have downloaded the toolchain, follow the steps in :ref:`Building-Examples` by seting the installation
+directory to match what you set it to earlier, assigning the path and source for your conda environment, and activating
+your env.
 
 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
@@ -19,7 +20,7 @@ directory. The location of the directory does not mater as long as the three des
 within it.
 
 HDL Files
-++++++++++
++++++++++
 
 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
@@ -31,7 +32,7 @@ your own makefiles or commands, you can specify your top level module name using
 ``symbiflow_synth``.
 
 Constraint File
-++++++++++++++++
++++++++++++++++
 
 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
@@ -43,7 +44,7 @@ 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
 Makefile for your designs. After following the directions listed there return to this page to

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