Developer documentation

CONTRIBUTING.rst

@@ -1,52 +1,8 @@
 Contributing
 ============
 
-Hey, thanks for your interest in contributing to Hawkmoth!
+See `developer documentation`_ or contributing_.
 
-Here's some initial guidance to help you contribute, which is hopefully better
-than nothing.
+.. _developer documentation: https://jnikula.github.io/hawkmoth/dev/developer/
 
-Broad Strokes
--------------
-
-In short, keep it simple.
-
-Simplicity applies both to the use and implementation of Hawkmoth. If a feature
-gets complicated, it probably does not belong in Hawkmoth. There are big fancy
-projects such as Doxygen and Breathe out there to comprehensively document C and
-C++ projects in Sphinx, but they're complicated to use and understand.
-
-Design Checklist
-----------------
-
-* Absolutely minimal parsing of the documentation comments.
-
-Contribution Checklist
-----------------------
-
-* New or modified features need test coverage. Add or update the tests in the
-  ``test`` directory accordingly. See `test/README.rst`_ for an overview of the
-  approach to testing.
-
-* Bug fixes need test coverage. Ideally add an expected failure test case
-  demonstrating the bug first, and then fix it.
-
-* Make sure the tests pass for every commit::
-
-    make test
-
-  or, to run the tests in a Docker container::
-
-    make docker-test
-
-* Make sure the static analysis (style checks, etc.) passes for every commit::
-
-    make check
-
-* User-visible changes need documentation.
-
-* Make sure the documentation build passes for every commit::
-
-    make html
-
-.. _test/README.rst: test/README.rst
+.. _contributing: doc/developer/contributing.rst

README.rst

@@ -120,11 +120,11 @@ checked out via ``git`` using this command::
 Please file bugs and feature requests as GitHub issues_. Contributions are
 welcome as GitHub pull requests.
 
-See `CONTRIBUTING.rst`_ for more details.
+See the `developer documentation`_ for details.
 
 .. _GitHub: https://github.com/jnikula/hawkmoth
 
-.. _CONTRIBUTING.rst: https://github.com/jnikula/hawkmoth/blob/master/CONTRIBUTING.rst
+.. _developer documentation: https://jnikula.github.io/hawkmoth/dev/developer/
 
 Dependencies
 ------------

doc/conf.py

@@ -83,7 +83,9 @@
     'extra_nav_links': {
         'GitHub': 'https://github.com/jnikula/hawkmoth',
         'PyPI': 'https://pypi.org/project/hawkmoth',
-    }
+    },
+    'sidebar_width': '280px',
+    'page_width': '1000px',
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,

doc/developer/contributing.rst

@@ -0,0 +1,52 @@
+.. _contributing:
+
+Contributing
+============
+
+Hey, thanks for your interest in contributing to Hawkmoth!
+
+Here's some initial guidance to help you contribute, which is hopefully better
+than nothing.
+
+Broad Strokes
+-------------
+
+In short, keep it simple.
+
+Simplicity applies both to the use and implementation of Hawkmoth. If a feature
+gets complicated, it probably does not belong in Hawkmoth. There are big fancy
+projects such as Doxygen and Breathe out there to comprehensively document C and
+C++ projects in Sphinx, but they're complicated to use and understand.
+
+Design Checklist
+----------------
+
+* Absolutely minimal parsing of the documentation comments.
+
+Contribution Checklist
+----------------------
+
+* New or modified features need test coverage. Add or update the tests in the
+  ``test`` directory accordingly. See :ref:`testing` for an overview of the
+  approach to testing.
+
+* Bug fixes need test coverage. Ideally add an expected failure test case
+  demonstrating the bug first, and then fix it.
+
+* Make sure the tests pass for every commit::
+
+    make test
+
+  or, to run the tests in a Docker container::
+
+    make docker-test
+
+* Make sure the static analysis (style checks, etc.) passes for every commit::
+
+    make check
+
+* User-visible changes need documentation.
+
+* Make sure the documentation build passes for every commit::
+
+    make html

doc/developer/index.rst

@@ -0,0 +1,12 @@
+.. _developer:
+
+Developer Documentation
+=======================
+
+Documentation for contributors and developers.
+
+.. toctree::
+   :maxdepth: 2
+
+   contributing
+   testing

doc/developer/testing.rst

@@ -0,0 +1,80 @@
+.. _testing:
+
+Testing
+=======
+
+This is a brief description of the approach to testing.
+
+The main idea is to compare documentation comments extracted from source to
+predefined, expected reStructuredText output.
+
+Test Files and Functions
+------------------------
+
+There are three test files, with different levels and approaches, run by
+``pytest``:
+
+* ``test_parser()`` in ``test_parser.py``
+
+  Test the parser directly. The documentation comments are extracted through the
+  parser Python interface.
+
+* ``test_cli()`` in ``test_cli.py``
+
+  Test the parser and the command-line interface. The documentation comments are
+  extracted through the command-line interface.
+
+* ``test_extension_text()`` and ``test_extension_html()`` in
+  ``test_extension.py``
+
+  Test the parser and the Sphinx extension, using two builders: text and
+  html. The documentation comments are extracted through the Sphinx build
+  process, running the extension.
+
+The above test functions are parametrized to be run for each test case (see
+below).
+
+Each test file contains abstractions depending on the approach, calling the
+generic ``run_test()`` function in ``testenv.py``, making the test files and
+functions just a thin glue layer.
+
+Test Cases
+----------
+
+The test functions described above are parametrized using what we call test
+cases. Each test case is defined by a ``.yaml`` file. The ``.yaml`` defines the
+configuration, the input C or C++ source file, the expected reStructuredText
+output file, and optionally a diagnostics (error messages) output file.
+
+The YAML is parsed using StrictYAML, using a schema defined in ``testenv.py``.
+
+The test approach, the relative path and the basename of the ``.yaml`` file
+define the parametrized test case name in ``pytest``, for example
+``test_parser[c/struct]``.
+
+Test Cases as Examples
+----------------------
+
+The examples in the documentation are generated from test cases under the
+``examples`` subdirectory, ensuring the examples actually work.
+
+``make update-examples`` runs ``update_examples.py`` to generate
+``doc/examples.rst`` from the example test cases.
+
+Running
+-------
+
+Run tests using ``make test``. This calls ``pytest``. The ``pytest-xdist``
+plugin parallelizes test execution.
+
+Running individual test approaches, for examples ``test_parser``::
+
+  $ pytest -k test_parser
+
+Run individual test cases, for example ``c/struct``::
+
+  $ pytest -k c/struct
+
+Combined, with verbose output, for example::
+
+  $ pytest -v -k test_cli[c/struct]

doc/index.rst

@@ -42,6 +42,7 @@ Contents:
    built-in-extensions
    tips
    troubleshooting
+   developer/index
 
 Indices and tables
 ==================

test/README.rst

@@ -1,78 +1,8 @@
 Testing
 =======
 
-This is a brief description of the approach to testing.
+See `developer documentation`_ or testing_.
 
-The main idea is to compare documentation comments extracted from source to
-predefined, expected reStructuredText output.
+.. _developer documentation: https://jnikula.github.io/hawkmoth/dev/developer/
 
-Test Files and Functions
-------------------------
-
-There are three test files, with different levels and approaches, run by
-``pytest``:
-
-* ``test_parser()`` in ``test_parser.py``
-
-  Test the parser directly. The documentation comments are extracted through the
-  parser Python interface.
-
-* ``test_cli()`` in ``test_cli.py``
-
-  Test the parser and the command-line interface. The documentation comments are
-  extracted through the command-line interface.
-
-* ``test_extension_text()`` and ``test_extension_html()`` in
-  ``test_extension.py``
-
-  Test the parser and the Sphinx extension, using two builders: text and
-  html. The documentation comments are extracted through the Sphinx build
-  process, running the extension.
-
-The above test functions are parametrized to be run for each test case (see
-below).
-
-Each test file contains abstractions depending on the approach, calling the
-generic ``run_test()`` function in ``testenv.py``, making the test files and
-functions just a thin glue layer.
-
-Test Cases
-----------
-
-The test functions described above are parametrized using what we call test
-cases. Each test case is defined by a ``.yaml`` file. The ``.yaml`` defines the
-configuration, the input C or C++ source file, the expected reStructuredText
-output file, and optionally a diagnostics (error messages) output file.
-
-The YAML is parsed using StrictYAML, using a schema defined in ``testenv.py``.
-
-The test approach, the relative path and the basename of the ``.yaml`` file
-define the parametrized test case name in ``pytest``, for example
-``test_parser[c/struct]``.
-
-Test Cases as Examples
-----------------------
-
-The examples in the documentation are generated from test cases under the
-``examples`` subdirectory, ensuring the examples actually work.
-
-``make update-examples`` runs ``update_examples.py`` to generate
-``doc/examples.rst`` from the example test cases.
-
-Running
--------
-
-Run tests using ``make test``. This calls ``pytest``. The ``pytest-xdist``
-plugin parallelizes test execution.
-
-Running individual test approaches, for examples ``test_parser``::
-
-  $ pytest -k test_parser
-
-Run individual test cases, for example ``c/struct``::
-
-  $ pytest -k c/struct
-
-Combined, with verbose output, for example::
-
-  $ pytest -v -k test_cli[c/struct]
+.. _testing: ../doc/developer/testing.rst