AtlanticWave-SDX Documentation

This repository contains some documentation for AtlanticWave-SDX project. This is work in progress -- most of our documentation currently lives elsewhere, and we are evaluating a GitHub based workflow of documenting the project.

The documentation sources live in [sources] directory. They are text documents with reStructuredText markup. HTML version of the documents is produced by processing them with Sphinx, and they are hosted at https://sdx-docs.readthedocs.io/.

Some additional information about reStruredText can be found in Sphinx manual.

Writing the docs

The setup will require Python. First, install the requirements, preferably in a virtual environment:

$ python3 -m venv venv --upgrade-deps
$ source venv/bin/activate
$ pip install -r requirements.txt

Then make the edits you want to files under source, and then run:

$ make html

The resulting HTML files will be under build/html.

Contributing to AtlanticWave-SDX Documentation

Please start a pull request. If the changes are large, it would be a good idea to file an issue first so that we can discuss them before you set out to spend considerable time.

Pull requests must pass two checks: one by a readthedocs.org PR builder, and another by a GitHub workflow that runs Sphinx with warnings enabled. They also must be approved by a reviewer before they can be merged.

Publishing the docs

Publishing is automated: https://sdx-docs.readthedocs.io/ will be updated when pull requests are merged to main branch of this repository.