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?
• symbolator to generate block level diagrams from Verilog examples.
• 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

FIXME: @xobs to add instructions here.