New Doc: docs/devguide/sphinx.rst (#261)

Author: Nusnus

docs/devguide/index.rst

@@ -19,3 +19,4 @@ are used and how to set up a local development environment.
 
     local-development-environment
     tox
+    sphinx

docs/devguide/sphinx.rst

@@ -0,0 +1,50 @@
+.. _sphinx:
+
+======================
+ Shpinx Documentation
+======================
+
+:Release: |version|
+:Date: |today|
+
+The plugin uses the :pypi:`sphinx_celery <sphinx_celery>` engine to generate the documentation.
+The documentation is written in reStructuredText format and is located in the ``docs`` directory of the repository.
+
+.. contents::
+    :local:
+    :depth: 2
+
+Building the documentation
+==========================
+
+To build the documentation, use the :ref:`tox_docs` tox environment.
+
+Live Documentation
+==================
+
+To serve the documentation locally, use the :ref:`tox_docs-livehtml` tox environment.
+
+Generate API Documentation
+==========================
+
+To generate the API documentation, use the :ref:`tox_docs-apidoc` tox environment.
+
+Linting the documentation
+=========================
+
+To lint the documentation, use the :ref:`tox_lint` tox environment, or these Makefile commands::
+
+    make -C ./docs apicheck
+    make -C ./docs linkcheck
+    make -C ./docs configcheck
+
+Makefile
+========
+
+The docs are managed using the following Makefile:
+
+.. literalinclude:: ../../docs/Makefile
+    :language: make
+    :caption: docs.Makefile
+    :start-after: .PHONY: help
+    :end-before: .PHONY: clean

docs/devguide/tox.rst

@@ -83,7 +83,7 @@ These configurations are used to define the base settings for the tox environmen
     :start-after: [testenv]
     :end-before: [testenv:xdist]
 
-.. _env_xdist:
+.. _tox_xdist:
 
 xdist
 =====
@@ -110,7 +110,7 @@ This environment is used to run the tests in parallel using both :pypi:`tox <tox
 It will run the test environments in parallel using the ``-p auto`` option from tox, and then run each environment itself in
 parallel using pytest-xdist with the ``-n auto`` option.
 
-It is slightly more efficient than the :ref:`env_xdist` tox environment, but less stable due to high resource usage.
+It is slightly more efficient than the :ref:`tox_xdist` tox environment, but less stable due to high resource usage.
 
 .. literalinclude:: ../../tox.ini
     :language: ini
@@ -143,6 +143,8 @@ To run this environment, use::
 
     tox -e mypy
 
+.. _tox_lint:
+
 lint
 ====
 
@@ -191,6 +193,8 @@ To run this environment, use::
 
     tox -e clean
 
+.. _tox_docs:
+
 docs
 ====
 
@@ -209,6 +213,8 @@ To run this environment, use::
 
     tox -e docs
 
+.. _tox_docs-livehtml:
+
 docs-livehtml
 =============
 
@@ -229,6 +235,8 @@ To run this environment, use::
 
     tox -e docs-livehtml
 
+.. _tox_docs-apidoc:
+
 docs-apidoc
 ===========