diff --git a/.github/travis/common.sh b/.github/travis/common.sh
new file mode 100644
index 0000000..b827736
--- /dev/null
+++ b/.github/travis/common.sh
@@ -0,0 +1,30 @@
+# Some colors, use it like following;
+# echo -e "Hello ${YELLOW}yellow${NC}"
+GRAY=' \033[0;30m'
+RED=' \033[0;31m'
+GREEN=' \033[0;32m'
+YELLOW=' \033[0;33m'
+PURPLE=' \033[0;35m'
+NC='\033[0m' # No Color
+
+SPACER="echo -e ${GRAY} - ${NC}"
+
+export -f travis_nanoseconds
+export -f travis_fold
+export -f travis_time_start
+export -f travis_time_finish
+export -f travis_wait
+export -f travis_jigger
+
+function start_section() {
+ travis_fold start "$1"
+ travis_time_start
+ echo -e "${PURPLE}${1}${NC}: $2${NC}"
+ echo -e "${GRAY}-------------------------------------------------------------------${NC}"
+}
+
+function end_section() {
+ echo -e "${GRAY}-------------------------------------------------------------------${NC}"
+ travis_time_finish
+ travis_fold end "$1"
+}
diff --git a/.github/travis/git-check.sh b/.github/travis/git-check.sh
new file mode 100755
index 0000000..b88c2db
--- /dev/null
+++ b/.github/travis/git-check.sh
@@ -0,0 +1,27 @@
+set -e
+
+source .github/travis/common.sh
+
+# Output any changes in the repository
+# ------------------------------------------------------------------------
+start_section git-status "Current git status"
+
+git diff
+
+$SPACER
+
+git status
+
+end_section git-status
+
+# Check there are not changes in the repository
+# ------------------------------------------------------------------------
+start_section git-check "Checking git repository isn't dirty"
+
+(
+ . "$(git --exec-path)/git-sh-setup"
+
+ require_clean_work_tree "continue" "Please run ``make README.rst`` to generate correct ``README.rst``."
+)
+
+end_section git-check
diff --git a/.travis.yml b/.travis.yml
index 6293756..89d4188 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -14,20 +14,22 @@ addons:
before_install:
- sudo locale-gen "en_US.UTF-8"
- export LANG="en_US.UTF-8"
+ - source .github/travis/common.sh
+ - rm README.rst && make README.rst && .github/travis/git-check.sh
- pip install git+https://github.com/antmicro/tuttest
- - tuttest README.md unnamed0 | bash -
+ - tuttest README.rst unnamed0 | bash -
jobs:
include:
- stage: SymbiFlow
install:
- - tuttest xc7/README.md unnamed0 | bash -
+ - tuttest xc7/README.rst unnamed0 | bash -
script:
- - tuttest xc7/README.md unnamed1 | bash -
+ - tuttest xc7/README.rst unnamed1,unnamed2,unnamed3,unnamed4,unnamed5 | bash -
- #
install:
- - tuttest eos-s3/README.md unnamed0 | bash -
+ - tuttest eos-s3/README.rst unnamed0 | bash -
script:
- - tuttest eos-s3/README.md unnamed1 | bash -
+ - tuttest eos-s3/README.rst unnamed1,unnamed2 | bash -
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..917c62a
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,5 @@
+include scripts/make/conda.mk
+
+README.rst: README.src.rst eos-s3/README.rst xc7/README.rst | $(CONDA_ENV_PYTHON)
+ @rm -f README.rst
+ $(IN_CONDA_ENV) rst_include include README.src.rst - > README.rst
diff --git a/README.md b/README.md
deleted file mode 100644
index f0f1425..0000000
--- a/README.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# SymbiFlow examples
-
-This repository provides example FPGA designs that can be built using the SymbiFlow open source toolchain.
-The examples target the Xilinx Artix-7 and the QuickLogic EOS S3 devices.
-
-The repository includes:
-
-* [eos-s3](./eos-s3) - Example FPGA designs for the QuickLogic EOS S3 series of parts:
-
- * Verilog code
- * Pin constraints files
- * Timing constraints files
- * Makefiles for running the SymbiFlow toolchain
-
-* [xc7](./xc7) - Example FPGA designs for the Xilinx 7 series of parts:
-
- * Verilog code
- * Pin constraints files
- * Timing constraints files
- * Makefiles for running the SymbiFlow toolchain
-
-* [.travis.yml](.travis.yml) - Travis CI configuration file
-
-## Toolchain installation
-
-This section describes how to install the toolchain. This procedure is divided in two steps:
-
-- Installing the Conda package manager
-- Downloading the architecture definitions and installing the toolchain
-
-1. Conda
-
-```bash
-wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O conda_installer.sh
-```
-
-2. Toolchain
-
-* For the Artix-7 devices see [xc7/README.md](xc7/README.md#setting-up-the-toolchain).
-
-
-* For the EOS S3 devices see [eos-s3/README.md](eos-s3/README.md#setting-up-the-toolchain).
-
-## Build Example Designs
-
-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
-
-### Example designs for the Artix-7 devices:
-
-* For the Artix-7 devices see [xc7/README.md](xc7/README.md#building-the-examples).
-
-### Example design for the EOS S3 devices:
-
-* For the EOS S3 devices see [eos-s3/README.md](eos-s3/README.md#building-the-examples).
-
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..660be00
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,145 @@
+SymbiFlow examples
+==================
+
+This repository provides example FPGA designs that can be built using the SymbiFlow open source toolchain.
+The examples target the Xilinx Artix-7 and the QuickLogic EOS S3 devices.
+
+The repository includes:
+
+* `eos-s3 `_ - Example FPGA designs for the QuickLogic EOS S3 series of parts:
+
+ * Verilog code
+ * Pin constraints files
+ * Timing constraints files
+ * Makefiles for running the SymbiFlow toolchain
+
+* `xc7 `_ - Example FPGA designs for the Xilinx 7 series of parts:
+
+ * Verilog code
+ * Pin constraints files
+ * Timing constraints files
+ * Makefiles for running the SymbiFlow toolchain
+
+* `.travis.yml <.travis.yml>`_ - Travis CI configuration file
+
+Toolchain installation
+----------------------
+
+This section describes how to install the toolchain. This procedure is divided in two steps:
+
+- Installing the Conda package manager
+- Downloading the architecture definitions and installing the toolchain
+
+#. Conda
+
+.. code:: bash
+
+ wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O conda_installer.sh
+
+#. Toolchain
+
+* For the Artix-7 devices:
+
+.. code:: bash
+
+ INSTALL_DIR="/opt/symbiflow/xc7"
+ bash conda_installer.sh -b -p $INSTALL_DIR/conda && rm conda_installer.sh
+ source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
+ conda env create -f xc7/environment.yml
+ conda activate xc7
+ wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/presubmit/install/477/20200714-082108/symbiflow-arch-defs-install-8eb88e76.tar.xz | tar -xJ --one-top-level=$INSTALL_DIR/install
+ conda deactivate
+
+* For the EOS S3 devices:
+
+.. code:: bash
+
+ export INSTALL_DIR="/opt/symbiflow/eos-s3"
+ bash conda_installer.sh -b -p $INSTALL_DIR/conda && rm conda_installer.sh
+ source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
+ conda env create -f eos-s3/environment.yml
+ conda activate eos-s3
+ wget -qO- https://quicklogic-my.sharepoint.com/:u:/p/kkumar/Eb7341Bq-XRAukVQ6oQ6PrgB-qdFbrsrPEON1yTa4krFSA?download=1 | tar -xJ -C $INSTALL_DIR
+ cp -r $INSTALL_DIR/conda/envs/eos-s3/share/yosys/* $INSTALL_DIR/conda/envs/eos-s3/share/
+ conda deactivate
+
+Build Example Designs
+---------------------
+
+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
+
+Example designs for the Artix-7 devices:
+****************************************
+
+* For the Artix-7 devices:
+
+Before building any example, prepare environment:
+
+.. code:: bash
+
+ export INSTALL_DIR="/opt/symbiflow/xc7"
+ # adding symbiflow toolchain binaries to PATH
+ export PATH="$INSTALL_DIR/install/bin:$PATH"
+ source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
+ conda activate xc7
+ git clone https://github.com/SymbiFlow/symbiflow-examples && cd symbiflow-examples
+
+To build the counter example, run the following commands:
+
+.. code:: bash
+
+ pushd xc7/counter_test && make clean && TARGET="arty_50" make && popd
+ pushd xc7/counter_test && make clean && TARGET="arty_100" make && popd
+ pushd xc7/counter_test && make clean && TARGET="basys3" make && popd
+
+To build the picosoc example, run the following commands:
+
+.. code:: bash
+
+ pushd xc7/picosoc_demo && make && popd
+
+To build the litex example, run the following commands:
+
+.. code:: bash
+
+ wget https://raw.githubusercontent.com/enjoy-digital/litex/master/litex_setup.py
+ chmod +x litex_setup.py
+ ./litex_setup.py init
+ ./litex_setup.py install
+ wget https://static.dev.sifive.com/dev-tools/riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14.tar.gz
+ tar -xf riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14.tar.gz
+ export PATH=$PATH:$PWD/riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14/bin/
+ pushd litex/litex/boards/targets && ./arty.py --toolchain symbiflow --cpu-type vexriscv --build && popd
+
+To build the linux-litex-demo example, run the following commands:
+
+.. code:: bash
+
+ pushd xc7/linux_litex_demo && make && popd
+
+Example design for the EOS S3 devices:
+**************************************
+
+* For the EOS S3 devices:
+
+Before building example, prepare environment:
+
+.. code:: bash
+
+ export INSTALL_DIR="/opt/symbiflow/eos-s3"
+ export PATH="$INSTALL_DIR/install/bin:$PATH"
+ source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
+ conda activate eos-s3
+
+ git clone https://github.com/SymbiFlow/symbiflow-examples && cd symbiflow-examples
+
+To build the example, run the following command:
+
+.. code:: bash
+
+ pushd eos-s3/btn_counter && make && popd
+
diff --git a/README.src.rst b/README.src.rst
new file mode 100644
index 0000000..9162f09
--- /dev/null
+++ b/README.src.rst
@@ -0,0 +1,80 @@
+SymbiFlow examples
+==================
+
+This repository provides example FPGA designs that can be built using the SymbiFlow open source toolchain.
+The examples target the Xilinx Artix-7 and the QuickLogic EOS S3 devices.
+
+The repository includes:
+
+* `eos-s3 `_ - Example FPGA designs for the QuickLogic EOS S3 series of parts:
+
+ * Verilog code
+ * Pin constraints files
+ * Timing constraints files
+ * Makefiles for running the SymbiFlow toolchain
+
+* `xc7 `_ - Example FPGA designs for the Xilinx 7 series of parts:
+
+ * Verilog code
+ * Pin constraints files
+ * Timing constraints files
+ * Makefiles for running the SymbiFlow toolchain
+
+* `.travis.yml <.travis.yml>`_ - Travis CI configuration file
+
+Toolchain installation
+----------------------
+
+This section describes how to install the toolchain. This procedure is divided in two steps:
+
+- Installing the Conda package manager
+- Downloading the architecture definitions and installing the toolchain
+
+#. Conda
+
+.. code:: bash
+
+ wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O conda_installer.sh
+
+#. Toolchain
+
+* For the Artix-7 devices:
+
+.. include:: xc7/README.rst
+ :start-after:.. toolchain_include_begin_label
+ :end-before:.. toolchain_include_end_label
+
+
+* For the EOS S3 devices:
+
+.. include:: eos-s3/README.rst
+ :start-after:.. toolchain_include_begin_label
+ :end-before:.. toolchain_include_end_label
+
+Build Example Designs
+---------------------
+
+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
+
+Example designs for the Artix-7 devices:
+****************************************
+
+* For the Artix-7 devices:
+
+.. include:: xc7/README.rst
+ :start-after:.. build_examples_include_begin_label
+ :end-before:.. build_examples_include_end_label
+
+Example design for the EOS S3 devices:
+**************************************
+
+* For the EOS S3 devices:
+
+.. include:: eos-s3/README.rst
+ :start-after:.. build_examples_include_begin_label
+ :end-before:.. build_examples_include_end_label
+
diff --git a/environment.yml b/environment.yml
new file mode 100644
index 0000000..0fb71f6
--- /dev/null
+++ b/environment.yml
@@ -0,0 +1,8 @@
+name: symbiflow-examples
+channels:
+ - defaults
+dependencies:
+ - python
+ - pip
+ - pip:
+ - -r file:requirements.txt
diff --git a/eos-s3/README.md b/eos-s3/README.md
deleted file mode 100644
index c4aed4f..0000000
--- a/eos-s3/README.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# SymbiFlow Toolchain Examples for QuickLogic EOS S3
-
-1. `btn_counter` - simple 4-bit counter driving LEDs. The design targets the [EOS S3 FPGA](https://www.quicklogic.com/products/eos-s3/).
-
-## Setting up the toolchain
-
-```bash
-export INSTALL_DIR="/opt/symbiflow/eos-s3"
-bash conda_installer.sh -b -p $INSTALL_DIR/conda && rm conda_installer.sh
-source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
-conda env create -f eos-s3/environment.yml
-conda activate eos-s3
-wget -qO- https://quicklogic-my.sharepoint.com/:u:/p/kkumar/Eb7341Bq-XRAukVQ6oQ6PrgB-qdFbrsrPEON1yTa4krFSA?download=1 | tar -xJ -C $INSTALL_DIR
-cp -r $INSTALL_DIR/conda/envs/eos-s3/share/yosys/* $INSTALL_DIR/conda/envs/eos-s3/share/
-conda deactivate
-```
-
-## Building the examples
-
-To build the examples, run the following commands:
-
-```bash
-export INSTALL_DIR="/opt/symbiflow/eos-s3"
-export PATH="$INSTALL_DIR/install/bin:$PATH"
-source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
-conda activate eos-s3
-
-git clone https://github.com/SymbiFlow/symbiflow-examples && cd symbiflow-examples
-pushd eos-s3/btn_counter && make && popd
-```
-
diff --git a/eos-s3/README.rst b/eos-s3/README.rst
new file mode 100644
index 0000000..57b36c7
--- /dev/null
+++ b/eos-s3/README.rst
@@ -0,0 +1,46 @@
+SymbiFlow Toolchain Examples for QuickLogic EOS S3
+==================================================
+
+#. ``btn_counter`` - simple 4-bit counter driving LEDs. The design targets the `EOS S3 FPGA `__.
+
+Setting up the toolchain
+------------------------
+
+.. toolchain_include_begin_label
+
+.. code:: bash
+
+ export INSTALL_DIR="/opt/symbiflow/eos-s3"
+ bash conda_installer.sh -b -p $INSTALL_DIR/conda && rm conda_installer.sh
+ source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
+ conda env create -f eos-s3/environment.yml
+ conda activate eos-s3
+ wget -qO- https://quicklogic-my.sharepoint.com/:u:/p/kkumar/Eb7341Bq-XRAukVQ6oQ6PrgB-qdFbrsrPEON1yTa4krFSA?download=1 | tar -xJ -C $INSTALL_DIR
+ cp -r $INSTALL_DIR/conda/envs/eos-s3/share/yosys/* $INSTALL_DIR/conda/envs/eos-s3/share/
+ conda deactivate
+
+.. toolchain_include_end_label
+
+Building the examples
+---------------------
+
+.. build_examples_include_begin_label
+
+Before building example, prepare environment:
+
+.. code:: bash
+
+ export INSTALL_DIR="/opt/symbiflow/eos-s3"
+ export PATH="$INSTALL_DIR/install/bin:$PATH"
+ source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
+ conda activate eos-s3
+
+ git clone https://github.com/SymbiFlow/symbiflow-examples && cd symbiflow-examples
+
+To build the example, run the following command:
+
+.. code:: bash
+
+ pushd eos-s3/btn_counter && make && popd
+
+.. build_examples_include_end_label
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..fa1f4f8
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1 @@
+rst_include
diff --git a/scripts/make/conda.mk b/scripts/make/conda.mk
new file mode 100644
index 0000000..26f0a42
--- /dev/null
+++ b/scripts/make/conda.mk
@@ -0,0 +1,97 @@
+SHELL := /bin/bash
+
+UNAME_S := $(shell uname -s)
+ifneq (, $(findstring Linux, $(UNAME_S)))
+ OSFLAG := Linux
+endif
+ifeq ($(UNAME_S), Darwin)
+ OSFLAG := MacOSX
+endif
+ifneq (, $(findstring Cygwin, $(UNAME_S)))
+ OSFLAG := Linux
+endif
+ifneq (, $(findstring MINGW, $(UNAME_S)))
+ OSFLAG := Linux
+endif
+
+MAKE_DIR := $(dir $(lastword $(MAKEFILE_LIST)))
+TOP_DIR := $(realpath $(MAKE_DIR)/../..)
+ENV_DIR := $(TOP_DIR)/env
+REQUIREMENTS_FILE := $(TOP_DIR)/requirements.txt
+ENVIRONMENT_FILE := $(TOP_DIR)/environment.yml
+
+CONDA_DIR := $(ENV_DIR)/conda
+DOWNLOADS_DIR := $(ENV_DIR)/downloads
+CONDA_PYTHON := $(CONDA_DIR)/bin/python
+CONDA_PKGS_DIR := $(DOWNLOADS_DIR)/conda-pkgs
+CONDA_PKGS_DEP := $(CONDA_PKGS_DIR)/urls.txt
+CONDA_ENV_NAME := symbiflow-examples
+CONDA_ENV_PYTHON := $(CONDA_DIR)/envs/$(CONDA_ENV_NAME)/bin/python
+IN_CONDA_ENV_BASE := source $(CONDA_DIR)/bin/activate &&
+IN_CONDA_ENV := $(IN_CONDA_ENV_BASE) conda activate $(CONDA_ENV_NAME) &&
+
+$(ENV_DIR): | $(DOWNLOADS_DIR)
+ mkdir -p $(END_DIR)
+
+$(DOWNLOADS_DIR):
+ mkdir -p $(DOWNLOADS_DIR)
+
+$(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh: | $(DOWNLOADS_DIR)
+ wget https://repo.anaconda.com/miniconda/Miniconda3-latest-$(OSFLAG)-x86_64.sh -O $(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh
+ chmod a+x $(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh
+
+$(CONDA_PKGS_DEP): $(CONDA_PYTHON)
+ $(IN_CONDA_ENV_BASE) conda config --system --add pkgs_dirs $(CONDA_PKGS_DIR)
+
+$(CONDA_PYTHON): $(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh
+ $(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh -p $(CONDA_DIR) -b -f
+ touch $(CONDA_PYTHON)
+
+$(CONDA_DIR)/envs: $(CONDA_PYTHON)
+ $(IN_CONDA_ENV_BASE) conda config --system --add envs_dirs $(CONDA_DIR)/envs
+
+$(CONDA_ENV_PYTHON): $(ENVIRONMENT_FILE) $(REQUIREMENTS_FILE) | $(CONDA_PYTHON) $(CONDA_DIR)/envs $(CONDA_PKGS_DEP)
+ $(IN_CONDA_ENV_BASE) conda env update --name $(CONDA_ENV_NAME) --file $(ENVIRONMENT_FILE)
+ touch $(CONDA_ENV_PYTHON)
+
+env: $(CONDA_ENV_PYTHON)
+ $(IN_CONDA_ENV) conda info
+
+.PHONY: env
+
+enter: $(CONDA_ENV_PYTHON)
+ $(IN_CONDA_ENV) bash
+
+.PHONY: enter
+
+clean:
+ rm -rf env/conda
+
+.PHONY: clean
+
+dist-clean:
+ rm -rf conda
+
+.PHONY: dist-clean
+
+
+FILTER_TOP = sed -e's@$(TOP_DIR)/@$$TOP_DIR/@'
+env-info:
+ @echo " Top level directory is: '$(TOP_DIR)'"
+ @echo " The version number is: '$$(git describe)'"
+ @echo " Git repository is using: $$(du -h -s $(TOP_DIR)/.git | sed -e's/\s.*//')" \
+ | $(FILTER_TOP)
+ @echo
+ @echo " Environment setup directory is: '$(ENV_DIR)'" \
+ | $(FILTER_TOP)
+ @echo " Download and cache directory is: '$(DOWNLOADS_DIR)' (using $$(du -h -s $(DOWNLOADS_DIR) | sed -e's/\s.*//'))" \
+ | $(FILTER_TOP)
+ @echo " Conda's directory is: '$(CONDA_DIR)' (using $$(du -h -s $(CONDA_DIR) | sed -e's/\s.*//'))" \
+ | $(FILTER_TOP)
+ @echo " Conda's packages download cache is: '$(CONDA_PKGS_DIR)' (using $$(du -h -s $(CONDA_PKGS_DIR) | sed -e's/\s.*//'))" \
+ | $(FILTER_TOP)
+ @echo " Conda's Python binary is: '$(CONDA_ENV_PYTHON)'"\
+ | $(FILTER_TOP)
+
+
+.PHONY: info
diff --git a/xc7/README.md b/xc7/README.md
deleted file mode 100644
index 266dedb..0000000
--- a/xc7/README.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# SymbiFlow Toolchain Examples for Xilinx 7 Series
-
-1. `counter` - simple 4-bit counter driving LEDs. The design targets the [Basys3 board](https://store.digilentinc.com/basys-3-artix-7-fpga-trainer-board-recommended-for-introductory-users/) and the [Arty board](https://store.digilentinc.com/arty-a7-artix-7-fpga-development-board-for-makers-and-hobbyists/).
-1. `picosoc` - [picorv32](https://github.com/cliffordwolf/picorv32) based SoC. The design targets the [Basys3 board](https://store.digilentinc.com/basys-3-artix-7-fpga-trainer-board-recommended-for-introductory-users/).
-1. `linux_litex` - [LiteX](https://github.com/enjoy-digital/litex) based system with Linux capable [VexRiscv core](https://github.com/SpinalHDL/VexRiscv). The design includes [DDR](https://github.com/enjoy-digital/litedram) and [Ethernet](https://github.com/enjoy-digital/liteeth) controllers. The design targets the [Arty board](https://store.digilentinc.com/arty-a7-artix-7-fpga-development-board-for-makers-and-hobbyists/).
-
-The Linux images for the `linux_litex` example can be built following the [linux on litex vexriscv](https://github.com/litex-hub/linux-on-litex-vexriscv) instructions.
-The `linux_litex` example is already provided with working Linux images.
-
-## Setting up the toolchain
-
-```bash
-INSTALL_DIR="/opt/symbiflow/xc7"
-bash conda_installer.sh -b -p $INSTALL_DIR/conda && rm conda_installer.sh
-source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
-conda env create -f xc7/environment.yml
-conda activate xc7
-wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/presubmit/install/477/20200714-082108/symbiflow-arch-defs-install-8eb88e76.tar.xz | tar -xJ --one-top-level=$INSTALL_DIR/install
-conda deactivate
-```
-
-## Building the examples
-
-To build the example, run the following commands:
-
-```bash
-export INSTALL_DIR="/opt/symbiflow/xc7"
-# adding symbiflow toolchain binaries to PATH
-export PATH="$INSTALL_DIR/install/bin:$PATH"
-source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
-conda activate xc7
-git clone https://github.com/SymbiFlow/symbiflow-examples && cd symbiflow-examples
-# counter example
-pushd xc7/counter_test && make clean && TARGET="arty_50" make && popd
-pushd xc7/counter_test && make clean && TARGET="arty_100" make && popd
-pushd xc7/counter_test && make clean && TARGET="basys3" make && popd
-# picosoc example
-pushd xc7/picosoc_demo && make && popd
-# litex example
-wget https://raw.githubusercontent.com/enjoy-digital/litex/master/litex_setup.py
-chmod +x litex_setup.py
-./litex_setup.py init
-./litex_setup.py install
-wget https://static.dev.sifive.com/dev-tools/riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14.tar.gz
-tar -xf riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14.tar.gz
-export PATH=$PATH:$PWD/riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14/bin/
-pushd litex/litex/boards/targets && ./arty.py --toolchain symbiflow --cpu-type vexriscv --build && popd
-# linux litex example
-pushd xc7/linux_litex_demo && make && popd
-```
-
diff --git a/xc7/README.rst b/xc7/README.rst
new file mode 100644
index 0000000..74da718
--- /dev/null
+++ b/xc7/README.rst
@@ -0,0 +1,79 @@
+SymbiFlow Toolchain Examples for Xilinx 7 Series
+================================================
+
+#. ``counter`` - simple 4-bit counter driving LEDs. The design targets the `Basys3 board `__ and the `Arty board `__.
+
+#. ``picosoc`` - `picorv32 `__ based SoC. The design targets the `Basys3 board `__.
+
+#. ``linux_litex`` - `LiteX `__ based system with Linux capable `VexRiscv core `__. The design includes `DDR `__ and `Ethernet `__ controllers. The design targets the `Arty board `__.
+
+The Linux images for the ``linux_litex`` example can be built following the `linux on litex vexriscv `__ instructions.
+The ``linux_litex`` example is already provided with working Linux images.
+
+Setting up the toolchain
+------------------------
+
+.. toolchain_include_begin_label
+
+.. code:: bash
+
+ INSTALL_DIR="/opt/symbiflow/xc7"
+ bash conda_installer.sh -b -p $INSTALL_DIR/conda && rm conda_installer.sh
+ source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
+ conda env create -f xc7/environment.yml
+ conda activate xc7
+ wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/presubmit/install/477/20200714-082108/symbiflow-arch-defs-install-8eb88e76.tar.xz | tar -xJ --one-top-level=$INSTALL_DIR/install
+ conda deactivate
+
+.. toolchain_include_end_label
+
+Building the examples
+---------------------
+
+.. build_examples_include_begin_label
+
+Before building any example, prepare environment:
+
+.. code:: bash
+
+ export INSTALL_DIR="/opt/symbiflow/xc7"
+ # adding symbiflow toolchain binaries to PATH
+ export PATH="$INSTALL_DIR/install/bin:$PATH"
+ source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
+ conda activate xc7
+ git clone https://github.com/SymbiFlow/symbiflow-examples && cd symbiflow-examples
+
+To build the counter example, run the following commands:
+
+.. code:: bash
+
+ pushd xc7/counter_test && make clean && TARGET="arty_50" make && popd
+ pushd xc7/counter_test && make clean && TARGET="arty_100" make && popd
+ pushd xc7/counter_test && make clean && TARGET="basys3" make && popd
+
+To build the picosoc example, run the following commands:
+
+.. code:: bash
+
+ pushd xc7/picosoc_demo && make && popd
+
+To build the litex example, run the following commands:
+
+.. code:: bash
+
+ wget https://raw.githubusercontent.com/enjoy-digital/litex/master/litex_setup.py
+ chmod +x litex_setup.py
+ ./litex_setup.py init
+ ./litex_setup.py install
+ wget https://static.dev.sifive.com/dev-tools/riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14.tar.gz
+ tar -xf riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14.tar.gz
+ export PATH=$PATH:$PWD/riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14/bin/
+ pushd litex/litex/boards/targets && ./arty.py --toolchain symbiflow --cpu-type vexriscv --build && popd
+
+To build the linux-litex-demo example, run the following commands:
+
+.. code:: bash
+
+ pushd xc7/linux_litex_demo && make && popd
+
+.. build_examples_include_end_label