From 7825784f5e4663ff6e5c8028a7a702be09f71c1d Mon Sep 17 00:00:00 2001 From: Larry Peterson Date: Wed, 7 Feb 2024 14:25:42 -0700 Subject: [PATCH] updated REAEME --- README | 23 -------------------- README.rst | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+), 23 deletions(-) delete mode 100644 README create mode 100644 README.rst diff --git a/README b/README deleted file mode 100644 index 8acd8f6..0000000 --- a/README +++ /dev/null @@ -1,23 +0,0 @@ -.. SPDX-FileCopyrightText: 2021 Open Networking Foundation - SPDX-License-Identifier: Apache-2.0 - -![example workflow](https://github.com/opennetworkinglab/aether-docs/actions/workflows/publish-docs.yml/badge.svg) - -Aether Docs -=========== - -This site contains Sphinx format documentation for the Aether project. -Please see the `Sphinx section of ONF Docs -`_ for instructions on how to -contribute to this documentation. - -Code of Conduct ---------------- - -We expect all ONF employees, member companies, and participants to abide by our -`Code of Conduct `_ - -If you are being harassed, notice that someone else is being harassed, or have -any other concerns involving someone’s welfare, please notify a member of the -ONF team or email conduct@opennetworking.org. - diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..2cf0c12 --- /dev/null +++ b/README.rst @@ -0,0 +1,64 @@ +.. SPDX-FileCopyrightText: 2021 Open Networking Foundation + SPDX-License-Identifier: Apache-2.0 + +![publish action](https://github.com/opennetworkinglab/aether-docs/actions/workflows/publish-docs.yml/badge.svg) + +Aether Docs +=========== + +This site contains Sphinx format documentation for the Aether project. + +Writing Documentation +--------------------- + +Docs are generated using :doc:`Sphinx ` using the +:doc:`reStructuredText ` syntax. +reStructuredText syntax references can be found here: + +* :doc:`Sphinx reStructuredText Primer ` +* `rst cheat sheet `_ + +Building Documentation +-------------------------- + +The documentation build process is stored in a ``Makefile``. Building docs +requires Python to be installed, and most steps will 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 Jenkins does on patchset validation, so: + +* ``make lint``: Check the formatting of documentation using `doc8 + `_. + +* ``make license``: Verifies licensing is correct using :ref:`REUSE + ` + +* ``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 built site, change the contents of the +``VERSION`` file to be released SemVer version. This will create a tag on the +repo. + +Then when ``make multiversion`` target can be used which will build all +versions tagged or branched on the remote to ``_build/multiversion``. This will +use 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.