Writing Documentation

Documentation is hosted at cfu-playground.readthedocs.io. It is built with Sphinx, which is a Python based document generator.

Development Setup

  1. cd to the docs/source directory.

  2. run pip3 install -r requirements.txt to install Sphinx and the components used by the CFU-Playground’s documentation.

  3. run make html to build the documentation.

Built documentation is in the docs/sourc/build/html directory. Use a web browser to view it.

Markdown or ReStructured Text

Documentation may be written in either Markdown or ReStructured Text. Either is acceptable, although ReStructuredText is Sphinx’s native format and you may find it slightly more flexible.

This document is written in ReStructuredText. There is also a example Markdown document in this folder.

Diagrams

We use Google Drawings for diagrams. Store diagrams in the cfu-playground-media Google Drive folder. It is publically readable, and if you’re working on diagrams, ask someone to put your diagram into this folder (you will still have write access).

To add the diagram to a ReStructured Text document, use File > Publish To the Web and select the HTML to embed an image. Add class="std" to choose standard size, centerered image. Don’t forget the alt tag.

Example showing how to embed a diagram using ReStructured Text:

.. raw:: html

   <img class="std"
       alt="Overview showing hardware, gateware and software layers"
       src="https://docs.google.com/drawings/d/e/2PACX-1vS_ydCYGB6yykkh3EXcmcv48NoC-o7ywYXUxiP8kzuFNfpQm-0K8cK73pgb3VqOCs0vPhtsPaX1Nvot/pub?w=958&amp;h=726">

Sub-pages