Skip to content

Latest commit

 

History

History
106 lines (82 loc) · 4.91 KB

README.md

File metadata and controls

106 lines (82 loc) · 4.91 KB
Raw

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.

Sample Data & Personas

Artemis documentation must use realistic examples and personas and must avoid the use of test data.

Using familiar information in the documentation is crucial because it simplifies the learning process for new users. Real-world scenarios demonstrate to users how to apply specific features within their own context, whereas test data can mislead and fails to reflect real use cases. Realistic examples and personas provide clarity and relevance, ensuring users can effectively understand and utilize Artemis.

Well-defined personas are vital for the development process. They not only help readers to understand the documentation, but also allow developers to better understand Artemis and its users. Many organizations use personas, the two blog posts below contain additional introduction and motivation for the topic:

Screenshots included in Artemis documentation must present realistic data. That includes but is not limited to:

  • realistic user, course and exercise names
  • realistic text passages, like submissions contents and problem statements

Screenshots included in Artemis documentation must not present any test data or server information. That includes but is not limited to:

  • Test Server and Development labels
  • test user, course and exercise names
  • Lorem ipsum and mock text passages, like submissions contents and problem statements
  • test server and localhost domains

Documentation Hosting

Read the Docs (RtD) hosts the Artemis documentation for the develop (latest) branch, as well as for git tags and branches of pull requests. You can switch the shown version at the bottom of the sidebar. The latest tag is always the stable version. For pull requests, the documentation is available at https://artemis-platform--{PR_NUMBER}.org.readthedocs.build/en/{PR_NUMBER}/. 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.txt

Running Sphinx Locally

To generate the documentation as a 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

Running Sphinx Locally with Docker

To generate the documentation as an HTML file, use the provided docker command from the project root:

docker run --rm -v ${PWD}/docs:/docs $(docker build -q -t sphinx -f docs/Dockerfile ./docs) make singlehtml

To auto-generate the documentation as HTML file and live-reload on changes, use the provided docker command from the project root:

docker run --rm -it -v ${PWD}/docs:/docs -p 8000:8000 $(docker build -q -t sphinx -f docs/Dockerfile ./docs)

Tool support

A list of useful tools to write documentation: