fomu-workshop/DEVELOPMENT.md

Developing the Workshop

The workshop is written in reStructuredText (rst) and generated using Sphinx.

It is hosted on Read The Docs and currently uses the Material Design style developed by Google through a slightly custom version of the sphinx_materialdesign_theme package.

It uses the sphinxcontrib-session extension to properly highlight the example sessions and to allow copying only the session lines.

Other sphinx extensions which are used include;

• sphinxcontrib-hdl-diagrams to generate nice diagrams from Verilog examples.
• sphinx-wavedrom to generate nice waveform diagrams. sphinxcontrib-wavedrom?
• sphinx_tabs to support tabs for different Linux / Windows / Mac OS X instructions.

Useful Resources for writing docs

• Sphinx RestructuredText Primer
• ReStructuredText directives
• Material Design Icons

Building Workshop Locally

On Mac & Linux

$ cd docs

Download conda environment with Python utilities:

$ make env
rm -rf env
make _download/Miniconda3-latest-Linux-x86_64.sh
make[1]: Entering directory '~/fomu-workshop/docs'
mkdir env
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O _download/Miniconda3-latest-Linux-x86_64.sh
--2020-01-03 10:15:07--  https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
Resolving repo.anaconda.com (repo.anaconda.com)... 104.16.131.3, 104.16.130.3, 2606:4700::6810:8203, ...
Connecting to repo.anaconda.com (repo.anaconda.com)|104.16.131.3|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 71785000 (68M) [application/x-sh]
Saving to: ‘_download/Miniconda3-latest-Linux-x86_64.sh’

_download/Miniconda3-latest-Linux-x86_64.sh                100%[==================>]  68.46M  1.29MB/s    in 17s

2020-01-03 10:15:29 (3.98 MB/s) - ‘_download/Miniconda3-latest-Linux-x86_64.sh’ saved [71785000/71785000]

chmod a+x _download/Miniconda3-latest-Linux-x86_64.sh
make[1]: Leaving directory '~/fomu-workshop/docs'
_download/Miniconda3-latest-Linux-x86_64.sh -p ~/fomu-workshop/docs/env -b -f
PREFIX=~/fomu-workshop/docs/env
Unpacking payload ...
Collecting package metadata (current_repodata.json): done
Solving environment: done

## Package Plan ##

  environment location: ~/fomu-workshop/docs/env

  added / updated specs:
    - _libgcc_mutex==0.1=main
    - asn1crypto==1.2.0=py37_0
    - ca-certificates==2019.10.16=0

<snip>

tk-8.6.10            | 3.2 MB    | ########################### | 100%
_libgcc_mutex-0.1    | 2 KB      | ########################### | 100%
xorg-libsm-1.2.3     | 25 KB     | ########################### | 100%
requests-2.22.0      | 84 KB     | ########################### | 100%
harfbuzz-2.4.0       | 1.5 MB    | ########################### | 100%
conda-package-handli | 942 KB    | ########################### | 100%
Preparing transaction: done
Verifying transaction: done
Executing transaction: done

Install dependencies:

$ pip install -r requirements.txt

Build the html output:

$ make html
Running Sphinx v2.3.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 21 source files that are out of date
updating environment: [config changed ('version')] 15 added, 0 changed, 6 removed
reading sources... [100%] verilog
writing output... [100%] verilog
copying images... [100%] _static/wishbone-usb-debug-bridge.png
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 15 warnings.

The HTML pages are in _build/html.
Copying tabs assets

Start your web browser:

$ xdg-open ./_build/html/index.html

On Windows

You may use either cmd.exe or Powershell. To begin with, set up venv. This may prompt you to install Python from the Microsoft Store:

$ cd docs
$ python -mvenv .

Activate the venv by running Activate.bat (if using cmd.exe) or Activate.ps1 (if using Powershell). You must do this any time you want to work on the documentation:

$ .\Scripts\Activate.ps1
(docs) $

You'll notice that the word (docs) is added to your command prompt. This indicates you're in a venv directory.

Next, install dependencies:

(docs) $ pip install -r requirements.txtCollecting sphinx_symbiflow_theme
  Cloning http://github.com/SymbiFlow/sphinx_materialdesign_theme.git (to revision master) to c:\users\sean\appdata\local\temp\pip-install-do82_l8w\sphinx-symbiflow-theme_75938b6aa0c04180962403b9b4b53fae
  Running command git clone -q http://github.com/SymbiFlow/sphinx_materialdesign_theme.git 'C:\Users\sean\AppData\Local\Temp\pip-install-do82_l8w\sphinx-symbiflow-theme_75938b6aa0c04180962403b9b4b53fae'
  Resolved http://github.com/SymbiFlow/sphinx_materialdesign_theme.git to commit 5a7c118c6485461de299366f638a0f3cc41ed4e8
Collecting sphinxcontrib-session
  Cloning https://github.com/mithro/sphinxcontrib-session.git to c:\users\sean\appdata\local\temp\pip-install-do82_l8w\sphinxcontrib-session_468cf0a370a04b079fd59a990969f629
  Running command git clone -q https://github.com/mithro/sphinxcontrib-session.git 'C:\Users\sean\AppData\Local\Temp\pip-install-do82_l8w\sphinxcontrib-session_468cf0a370a04b079fd59a990969f629'
  Resolved https://github.com/mithro/sphinxcontrib-session.git to commit f9e959a696ba02d874ffc291a3b83a4458c1bad6

<snip>

    Running setup.py install for sphinxcontrib-session ... done
    Running setup.py install for sphinxcontrib-hdl-diagrams ... done
    Running setup.py install for sphinx-symbiflow-theme ... done
Successfully installed Jinja2-3.0.3 MarkupSafe-2.0.1 Pygments-2.11.2 alabaster-0.7.12 appdirs-1.4.4 attrdict-2.0.1 babel-2.9.1 cairocffi-1.3.0 cairosvg-2.5.2 certifi-2021.10.8 cffi-1.15.0 charset-normalizer-2.0.10 colorama-0.4.4 cssselect2-0.4.1 defusedxml-0.7.1 docutils-0.16 idna-3.3 imagesize-1.3.0 livereload-2.6.3 nmigen-0.2 packaging-21.3 pillow-9.0.0 pycparser-2.21 pyparsing-3.0.7 pytz-2021.3 pyvcd-0.1.7 requests-2.27.1 six-1.16.0 snowballstemmer-2.2.0 sphinx-3.5.4 sphinx-autobuild-2021.3.14 sphinx-symbiflow-theme-0.1.11 sphinx-tabs-3.2.0 sphinxcontrib-applehelp-1.0.2 sphinxcontrib-devhelp-1.0.2 sphinxcontrib-hdl-diagrams-0.0.dev0 sphinxcontrib-htmlhelp-2.0.0 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-1.0.3 sphinxcontrib-serializinghtml-1.1.5 sphinxcontrib-session-0.0.1 sphinxcontrib-wavedrom-3.0.2 svgwrite-1.4.1 tinycss2-1.1.1 tornado-6.1 urllib3-1.26.8 wasmtime-0.30.0 wavedrom-2.0.3.post2 webencodings-0.5.1 xcffib-0.11.1 yowasp-yosys-0.13.dev285
WARNING: You are using pip version 21.2.4; however, version 22.0 is available.
You should consider upgrading via the 'E:\Code\Fomu\workshop\docs\Scripts\python.exe -m pip install --upgrade pip' command.
(docs) $

Build HTML:

(docs) $ sphinx-build -M html . _build
Running Sphinx v3.5.4

<snip>

dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 20 warnings.

The HTML pages are in _build\html.
(docs) $

Start your web browser:

$ explorer ./_build/html/index.html