Development

Includes
  • Debian based, per vscode devcontainer recommended base

  • Lint: flake8

  • Formater: black

  • QoL plugins for vscode

  • Added programs
    • jq

    • poetry

Setup

  1. You need to have Visual Studio Code a.k.a vscode installed with Remote Development Extension Pack.

  2. Fork this repo

  3. Open the forked project in vscode

  4. You will see this dialog box

_images/open_with_devcontainer.png
  1. Press Reopen in Container

  2. Now you will ready to start coding. You have all things you need installed. Check Development for what is installed.

Docs

All commands for docs need to run from the docs folder

Docs are written in rst and we are using sphinx to generate all the needed output.

Note

Don’t forget to run make clean when sphinx gets weird

To audobuild html docs when developing

sphinx-autobuild . _build/html/ --watch ../.
# OR use the alias
autobuild-html-docs

Tests

Test are using pytest

Intersphinx

Intersphinx is a fantastic tool that enables you to automatic cross-reference and generating links other projects that uses sphinx. Run scripts/docs_helper.py and use the interactive guide to help with linking

  • rtd docs about intersphinx

  • sphobjinv is a tool to help linking with cross-reference

Diagrams

There is support for automatically generating diagrams from text with kroki See https://github.com/sphinx-contrib/kroki for more info

blockdiag { Kroki -> generates -> "Block diagrams"; Kroki -> is -> "very easy!";  Kroki [color = "greenyellow"]; "Block diagrams" [color = "pink"]; "very easy!" [color = "orange"]; }

PDF output

Output to pdf is supported with rinohtype

To build pdf run:

# (cd docs)
sphinx-build -b rinoh . _build/rinoh -t pdf
# OR use the alias
build-pdf