docs: add section 'Development'

Signed-off-by: Unai Martinez-Corral <umartinezcorral@antmicro.com>

README.rst

@@ -1,10 +1,6 @@
 F4PGA examples
 ==============
 
-Please refer to the `project documentation <https://f4pga-examples.readthedocs.io>`_
-for a proper guide on how to run these examples as well as instructions on how to build and
-compile your own HDL designs using the F4PGA toolchain.
-
 .. image:: https://github.com/chipsalliance/f4pga-examples/workflows/doc-test/badge.svg?branch=master
    :target: https://github.com/chipsalliance/f4pga-examples/actions
 
@@ -12,60 +8,27 @@ compile your own HDL designs using the F4PGA toolchain.
    :target: https://f4pga-examples.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status
 
-This repository provides example FPGA designs that can be built using the
+This repository provides example FPGA designs that can be built using the F4PGA open source toolchain.
-F4PGA open source toolchain. These examples target the Xilinx 7-Series and
+These examples target the Xilinx 7-Series and the QuickLogic EOS S3 devices.
-the QuickLogic EOS S3 devices.
+
+Please refer to the `project documentation <https://f4pga-examples.readthedocs.io>`_ for a proper guide on how to run
+these examples as well as instructions on how to build and compile your own HDL designs using the F4PGA toolchain.
 
 The repository includes:
 
 * `xc7/ <./xc7>`_ and `eos-s3/ <./eos-s3>`_ - Examples for Xilinx 7-Series and EOS-S3 devices, including:
 
   * Verilog code
+
   * Pin constraints files
+
   * Timing constraints files
+
   * Makefiles for running the F4PGA toolchain
+
 * `docs/ <./docs>`_ - Guide on how to get started with F4PGA and build provided examples
+
 * `.github/ <./.github>`_ - Directory with CI configuration and scripts
 
-The examples provided by this repository are automatically built by extracting
+The examples provided in this repository are automatically built and tested in CI by extracting necessary code snippets
-necessary code snippets with `tuttest <https://github.com/antmicro/tuttest>`_.
+with `tuttest <https://github.com/antmicro/tuttest>`_.
-
-Building those docs
--------------------
-
-To build Sphinx documentation, you need at least Python 3.6. You will also need
-to install Sphinx v3.3.0 and additional dependencies, which you can get with
-``pip``::
-
-   pip install -r docs/requirements.txt
-
-Next, just run::
-
-   make -C docs html
-
-The output will be found in the ``docs/_build/html`` directory.
-
-Running "CI" locally
---------------------
-
-The CI uses a bunch of scripts in the `.github/scripts/ <./.github/scripts>`_
-directory to execute the needed tests. You can use the same scripts locally
-to test without having to wait for the online CIs to pass if you
-want to quickly test stuff.
-
-For this, you will need `tuttest <https://github.com/antmicro/tuttest/>`_,
-which you can install with::
-
-    pip install git+https://github.com/antmicro/tuttest
-
-* ``<fpga-family>`` is one of ``{eos-s3, xc7}`` (the two currently
-  covered platforms - EOS-S3 and Xilinx series 7).
-* ``<os>`` is one of ``{ubuntu, debian, centos}`` (currently supported operating systems).
-
-To install the toolchain (just the first time), run::
-
-   .github/scripts/install-toolchain.sh <fpga-family> <os> | bash -c "$(cat /dev/stdin)"
-
-To build all the examples locally, just run::
-
-   .github/scripts/build-examples.sh <fpga-family>  | bash -c "$(cat /dev/stdin)"

docs/development/building-docs.rst

@@ -0,0 +1,13 @@
+Building the documentation
+##########################
+
+To build Sphinx documentation, you need at least Python 3.6.
+You will also need to install Sphinx v3.3.0 and additional dependencies, which you can get with ``pip``::
+
+   pip install -r docs/requirements.txt
+
+Next, just run::
+
+   make -C docs html
+
+The output will be found in the ``docs/_build/html`` directory.

docs/development/running-ci-locally.rst

@@ -0,0 +1,22 @@
+Running "CI" locally
+####################
+
+The CI uses a bunch of scripts in the `.github/scripts/ <./.github/scripts>`_ directory to execute the needed tests.
+You can use the same scripts locally to test without having to wait for the online CIs to pass if you want to quickly
+test stuff.
+
+For this, you will need `tuttest <https://github.com/antmicro/tuttest/>`_, which you can install with::
+
+    pip install git+https://github.com/antmicro/tuttest
+
+* ``<fpga-family>`` is one of ``{eos-s3, xc7}`` (the two currently covered platforms - EOS-S3 and Xilinx series 7).
+
+* ``<os>`` is one of ``{ubuntu, debian, centos}`` (currently supported operating systems).
+
+To install the toolchain (just the first time), run::
+
+   .github/scripts/install-toolchain.sh <fpga-family> <os> | bash -c "$(cat /dev/stdin)"
+
+To build all the examples locally, just run::
+
+   .github/scripts/build-examples.sh <fpga-family>  | bash -c "$(cat /dev/stdin)"

docs/index.rst

@@ -50,3 +50,9 @@ currently targeting chips from multiple vendors, e.g.:
 
    project-f
    basys3
+
+.. toctree::
+   :caption: Development
+
+   development/building-docs
+   development/running-ci-locally