From 6716b7246ffde9b0366e6a0452a1772abf1b67b0 Mon Sep 17 00:00:00 2001 From: umarcor Date: Sat, 10 Oct 2020 14:04:49 +0200 Subject: [PATCH] readme: add shields/badges, move 'Development' sections to a separated file --- DEVELOPMENT.md | 125 +++++++++++++++++++++++++++++++++++++++ README.md | 154 ++++++++----------------------------------------- 2 files changed, 150 insertions(+), 129 deletions(-) create mode 100644 DEVELOPMENT.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..7e6599e --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,125 @@ +# Developing the Workshop + +The workshop is written in +[reStructuredText (rst)](https://en.wikipedia.org/wiki/ReStructuredText) and +[generated using Sphinx](https://www.sphinx-doc.org/en/master/). + +It is hosted on [Read The Docs](http://readthedocs.org/) and currently uses the +[Material Design style](https://material.io/) developed by Google through +[a slightly custom version of the `sphinx_materialdesign_theme` package](http://github.com/SymbiFlow/sphinx_materialdesign_theme). + +It uses the [`sphinxcontrib-session` extension](https://github.com/mithro/sphinxcontrib-session) +to properly highlight the example sessions and to allow copying only the +session lines. + +Other sphinx extensions which are used include; + +- [`sphinxcontrib-hdl-diagrams`](http://sphinxcontrib-hdl-diagrams.rtfd.io/) to + generate nice diagrams from Verilog examples. +- [`sphinx-wavedrom`](https://github.com/bavovanachte/sphinx-wavedrom) to + generate [nice waveform diagrams](http://wavedrom.com/). `sphinxcontrib-wavedrom`? +- [`symbolator`](https://kevinpt.github.io/symbolator/) to generate block level + diagrams from Verilog examples. +- [`sphinx_tabs`](https://github.com/djungelorm/sphinx-tabs) to support tabs + for different Linux / Windows / Mac OS X instructions. + +## Useful Resources for writing docs + +- [Sphinx RestructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) +- [ReStructuredText directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html) +- [Material Design Icons](https://material.io/resources/icons/) + +# Building Workshop Locally + +## On Mac & Linux + +```shell-session +$ cd docs +``` +Download conda environment with Python utilities: + +```shell-session +$ 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 + + + +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: + +```shell-session +$ pip install -r requirements.txt +``` + +Build the html output: + +```shell-session +$ 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: + +```shell-session +$ xdg-open ./_build/html/index.html +``` + +## On Windows + +FIXME: @xobs to add instructions here. diff --git a/README.md b/README.md index 71647b2..63b5937 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,27 @@ -# [Fomu Workshop](https://workshop.fomu.im/) +

+ +

-![Hi, I'm Fomu!](docs/_static/logo.png "Fomu logo") +

+ + + 'test' workflow status + 'doc' workflow status +

Hi, I'm Fomu! [This workshop](https://workshop.fomu.im/) covers the basics of -Fomu in a top-down approach. We'll start out by learning what Fomu is, how to -load software into Fomu, and finally how to write software for Fomu. +Fomu in a top-down approach. We'll start out by learning **what** Fomu is, **how to +load software** into Fomu, **how to write software** for Fomu and finally **how to +write hardware** for Fomu. + +

+ + +

FPGAs are complex, weird things, so we'll take a gentle approach and start out by treating it like a Python interpreter first, and gradually peel away layers @@ -12,7 +29,7 @@ until we're writing our own hardware registers. You can take a break at any time and explore! Stop when you feel the concepts are too unfamiliar, or plough on and dig deep into the world of hardware. -The contents of this workshop is published at https://workshop.fomu.im +The contents of this workshop is published at [workshop.fomu.im](https://workshop.fomu.im). ## Repository Contents @@ -26,128 +43,7 @@ The contents of this workshop is published at https://workshop.fomu.im - [verilog](./verilog) - The files required for the [Verilog on Fomu section of the workshop](https://workshop.fomu.im/en/latest/verilog.html). -# Developing the Workshop +# Development -The workshop is written in -[reStructuredText (rst)](https://en.wikipedia.org/wiki/ReStructuredText) and -[generated using Sphinx](https://www.sphinx-doc.org/en/master/). - -It is hosted on [Read The Docs](http://readthedocs.org/) and currently uses the -[Material Design style](https://material.io/) developed by Google through -[a slightly custom version of the `sphinx_materialdesign_theme` package](http://github.com/SymbiFlow/sphinx_materialdesign_theme). - -It uses the [`sphinxcontrib-session` extension](https://github.com/mithro/sphinxcontrib-session) -to properly highlight the example sessions and to allow copying only the -session lines. - -Other sphinx extensions which are used include; - -- [`sphinxcontrib-hdl-diagrams`](http://sphinxcontrib-hdl-diagrams.rtfd.io/) to - generate nice diagrams from Verilog examples. -- [`sphinx-wavedrom`](https://github.com/bavovanachte/sphinx-wavedrom) to - generate [nice waveform diagrams](http://wavedrom.com/). `sphinxcontrib-wavedrom`? -- [`symbolator`](https://kevinpt.github.io/symbolator/) to generate block level - diagrams from Verilog examples. -- [`sphinx_tabs`](https://github.com/djungelorm/sphinx-tabs) to support tabs - for different Linux / Windows / Mac OS X instructions. - -## Useful Resources for writing docs - -- [Sphinx RestructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) -- [ReStructuredText directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html) -- [Material Design Icons](https://material.io/resources/icons/) - -# Building Workshop Locally - -## On Mac & Linux - -```shell-session -$ cd docs -``` -Download conda environment with Python utilities: - -```shell-session -$ 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 - - - -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: - -```shell-session -$ pip install -r requirements.txt -``` - -Build the html output: - -```shell-session -$ 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: - -```shell-session -$ xdg-open ./_build/html/index.html -``` - -## On Windows - -FIXME: @xobs to add instructions here. +For guidelines about how to develop the workshop or how to build the workshop +locally, see [DEVELOPMENT](DEVELOPMENT.md).