README.md

Artemis Documentation

We use Sphinx for creating the Artemis documentation using reStructuredText (RST). To get started with RST, check out the Quickstart or this cheatsheet.

Documentation Hosting

Read the Docs (RtD) hosts the Artemis documentation for the develop (latest) branch, as well as for git tags. The latest tag is always the stable version. RtD will build and deploy changes automatically.

Installing Sphinx Locally

Sphinx can run locally to generate the documentation in HTML and other formats. You can install Sphinx using pip or choose a system-wide installation instead. When using pip, consider using Python virtual environments.

pip install -r requirements.txt

or

pip3 install -r requirements.txt

The Installing Sphinx documentation explains more install options. For macOS, it is recommended to install it using homebrew:

brew install sphinx-doc
brew link sphinx-doc --force
pip3 install -r requirements.txtclient-tests.rst

Running Sphinx Locally

To generate the documentation as single HTML file, use the provided Makefile/make.bat files in the folder docs:

# maxOS / Linux
make singlehtml

# Windows
make.bat singlehtml

Using sphinx-autobuild, the browser will live-reload on changes, ideal for viewing changes while writing documentation:

# maxOS / Linux
make livehtml

# Windows
make.bat livehtml

Tool support

A list of useful tools to write documentation:

• reStructuredText for Visual Studio Code
• LanguageTool for Visual Studio Code: Provides offline grammar checking
• ReStructuredText for IntelliJ