mirror of
https://github.com/im-tomu/fomu-workshop.git
synced 2024-09-20 03:10:12 +00:00
readme: add shields/badges, move 'Development' sections to a separated file
This commit is contained in:
umarcor
parent
846a0e735e
commit
6716b7246f
125
DEVELOPMENT.md
Normal file
125
DEVELOPMENT.md
Normal file
@ -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
|
||||
|
||||
<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:
|
||||
|
||||
```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.
|
||||
154
README.md
154
README.md
@ -1,10 +1,27 @@
|
||||
# [Fomu Workshop](https://workshop.fomu.im/)
|
||||
<p align="center">
|
||||
<a title="FPGA Tomu (Fomu) Workshop" href="https://workshop.fomu.im/"><img width="600px" src="docs/_static/logo.png"/></a>
|
||||
</p>
|
||||
|
||||
|
||||
<p align="center">
|
||||
<a title="Nightly build" href="https://workshop.fomu.im/"><img src="https://img.shields.io/website.svg?label=workshop.fomu.im&longCache=true&style=flat-square&url=http%3A%2F%2Fworkshop.fomu.im%2Findex.html&logo=Read%20the%20Docs&logoColor=fff"></a><!--
|
||||
-->
|
||||
<a title="Nightly build" href="https://im-tomu.github.io/fomu-workshop"><img src="https://img.shields.io/website.svg?label=im-tomu.github.io%2Ffomu-workshop&longCache=true&style=flat-square&url=http%3A%2F%2Fim-tomu.github.io%2Ffomu-workshop%2Findex.html&logo=GitHub&logoColor=fff"></a><!--
|
||||
-->
|
||||
<a title="'test' workflow status" href="https://github.com/im-tomu/fomu-workshop/actions?query=workflow%3Atest"><img alt="'test' workflow status" src="https://img.shields.io/github/workflow/status/im-tomu/fomu-workshop/test?longCache=true&style=flat-square&label=test&logo=Github%20Actions&logoColor=fff"></a><!--
|
||||
-->
|
||||
<a title="'doc' workflow status" href="https://github.com/im-tomu/fomu-workshop/actions?query=workflow%3Adoc"><img alt="'doc' workflow status" src="https://img.shields.io/github/workflow/status/im-tomu/fomu-workshop/doc?longCache=true&style=flat-square&label=doc&logo=Github%20Actions&logoColor=fff"></a><!--
|
||||
-->
|
||||
</p>
|
||||
|
||||
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.
|
||||
|
||||
<p align="center">
|
||||
<a title="FPGA Tomu (Fomu) Workshop" href="https://workshop.fomu.im/"><img src="docs/_static/hw-pvt-back-bare-small.jpg"/></a>
|
||||
<a title="FPGA Tomu (Fomu) Workshop" href="https://workshop.fomu.im/"><img src="docs/_static/hw-pvt-front-bare-small.jpg"/></a>
|
||||
</p>
|
||||
|
||||
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
|
||||
|
||||
<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:
|
||||
|
||||
```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).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user