https://github.com/opennetworkinglab/aether-docs
https://github.com/opennetworkinglab/aether-docs
Last synced: 8 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/opennetworkinglab/aether-docs
- Owner: opennetworkinglab
- Created: 2024-01-18T21:52:37.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2025-03-06T20:37:50.000Z (over 1 year ago)
- Last Synced: 2025-04-10T03:13:23.468Z (about 1 year ago)
- Language: Python
- Size: 15.3 MB
- Stars: 4
- Watchers: 3
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.rst
- License: LICENSES/Apache-2.0.txt
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
.. SPDX-FileCopyrightText: 2021 Open Networking Foundation
SPDX-License-Identifier: Apache-2.0
.. |pub-badge| image:: https://github.com/opennetworkinglab/aether-docs/actions/workflows/publish-docs.yml/badge.svg
|pub-badge|
Aether Docs
===========
This repo contains Sphinx-formated documentation for the Aether project.
Writing Documentation
---------------------
Docs are generated using `Sphinx `_ with
`reStructuredText `_ syntax.
A cheat sheet for reStructuredText can be found `here `_.
Building Documentation
--------------------------
The documentation build process is stored in a ``Makefile``. Building
docs requires Python to be installed, and most steps create a
virtualenv (usually ``venv-docs``) which contains the required tools.
You may also need to install the ``enchant`` C library using your
system's package manager for the spelling checker to function
properly.
Run ``make html`` to generate html documentation in ``_build/html``.
There is also a test target, ``make test``, which will run all the following
checks. This is what happens to validate a patchset.
* ``make lint``: Check the formatting of documentation using `doc8
`_.
* ``make spelling``: Checks spelling on all documentation. If there are
additional words that are correctly spelled but not in the dictionary
(acronyms, nouns, etc.) please add them to the ``dict.txt`` file, which
should be alphabetized using ``sort``
* ``make linkcheck``: Verifies that links in the document are working and
accessible, using Sphinx's built in linkcheck tool. If there are links that
don't work with this, please see the ``linkcheck_ignore`` section of
``conf.py``.
Versioning Documentation
----------------------------------
To change the version shown on the build site, change the contents of the
``VERSION`` file to be released SemVer version. This will create a tag on the
repo.
The ``make multiversion`` target can then be used to build all
versions tagged or branched on the remote to ``_build/multiversion``. This
uses a fork of `sphinx-multiversion
`_ to build multiple versions
and a menu on the site.
There are variables in ``conf.py`` to determine which tags/branches to build.