Initial commit to ONF Docs site
Change-Id: Ic882d6c7cc2f17a8fe74acee5cb70352b04aada2
diff --git a/docs/sphinx.rst b/docs/sphinx.rst
new file mode 100644
index 0000000..05bcba9
--- /dev/null
+++ b/docs/sphinx.rst
@@ -0,0 +1,132 @@
+Sphinx
+======
+
+Docs are generated using :doc:`Sphinx <sphinx:usage/index>` using the
+:doc:`reStructuredText <sphinx:usage/restructuredtext/basics>` syntax.
+
+Sphinx was chosen because it's widely used (Python official docs, Linux Kernel,
+Read the Docs, etc.), open source, actively maintained, has code highlighting,
+and a good client-side search implementation.
+
+Writing Documentation
+---------------------
+
+reStructuredText syntax references can be found here:
+
+* :doc:`Sphinx reStructuredText Primer <sphinx:usage/restructuredtext/basics>`
+* `rst cheat sheet <https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst>`_
+
+rST creates headings by underlining the heading with a series of symbol
+characters. There is no specific required order for these, but for consistency
+most ONF docs use the following symbols/order to represent heading levels::
+
+ H1: =
+ H2: -
+ H3: "
+ H4: '
+ H5: ^
+ H6: +
+
+Linking within Documentation
+""""""""""""""""""""""""""""
+
+
+Referencing other Documentation
+"""""""""""""""""""""""""""""""
+
+Other Sphinx-built documentation, both ONF and non-ONF can be linked to using
+:doc:`InterSphinx <sphinx:usage/extensions/intersphinx>`, which allows you to
+create links that will work even if the other site moves or reorganizes
+content.
+
+New InterSphinx reference requires modifying the ``intersphinx_mapping``
+variables of the ``conf.py`` file.
+
+You can see all link targets available on a remote Sphinx's docs by running::
+
+ python -msphinx.ext.intersphinx http://otherdocs/objects.inv
+
+More information about InterSphinx:
+
+* :doc:`Read the Docs InterSphinx Guide <rtd:guides/intersphinx>`
+
+Adding Images and Diagrams
+""""""""""""""""""""""""""
+
+There are multiple ways to add images and diagrams to the documentation.
+
+Generally, you should prefer using `SVG
+<https://en.wikipedia.org/wiki/Scalable_Vector_Graphics>`_ images, as these can
+be scaled to any size without quality loss.
+
+If you're creating diagrams, there are multiple tools available.
+:doc:`Graphviz <sphinx:usage/extensions/graphviz>` can render inline text-based
+graphs definitions and diagrams within the documentation, and is best choice for
+simple diagrams.
+
+More complex diagrams can be created in `Diagrams.net/Draw.io
+<https://www.diagrams.net/>`_ format, which is available as a standalone app,
+web app, or integrated with various other tools like Google Workspace. When
+saving these diagrams, use the SVG format, and check the **Include a copy of my
+diagram** box. This will let someone open the SVG later within Diagrams.net
+from file saved in the documentation and edit it without any loss in
+functionality or quality.
+
+The last resort is to use raster (bitmap) images. If they're drawings or screen
+captures, use the `PNG
+<https://en.wikipedia.org/wiki/Portable_Network_Graphics>`_ format. Consider
+optimizing the PNG files with a tool like `OptiPNG
+<http://optipng.sourceforge.net/>`_, or `pngquant <https://pngquant.org/>`_ to
+save space and data transfer required.
+
+If you need to include a photograph, use `JPEG
+<https://en.wikipedia.org/wiki/JPEG>`_.
+
+Building the 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
+ <https://github.com/PyCQA/doc8>`_.
+
+* ``make license``: Verifies licensing is correct using :ref:`REUSE
+ <policies/licensing:REUSE License Tool>`
+
+* ``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``.
+
+Some sites may have the ability to build a PDF file of the documentation using
+``make latexpdf``. This requires that you have a recent LaTeX installation and
+``latexmk`` installed.
+
+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
+<https://github.com/Holzhaus/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.