Merge pull request #876 from ix5/docs-testing

Docs testing

Makefile

@@ -86,7 +86,7 @@ coverage: $(ISSO_PY_SRC)
 	coverage report --omit='*/tests/*'
 
 test: $($ISSO_PY_SRC)
-	pytest --doctest-modules isso/
+	PYTHONPATH=. pytest --doctest-modules isso/tests/
 
 clean:
 	rm -f $(ISSO_JS_DST)

docs/docs/contributing/documentation.rst

@@ -43,7 +43,7 @@ You will need to have the latest version of the ``Sphinx`` documentation generat
 
 .. warning:: Please avoid using the version installed by your operating system
    since it may be severely outdated and throw errors with Isso's theme. Isso's
-   docs need at least version 4.5.0.
+   docs need **at least Sphinx version 4.5.0**.
 
 Install via pip:
 
@@ -60,6 +60,9 @@ Build the docs:
 
    (.venv) $ make site
 
+You can then view the generated docs by starting a local server with
+``cd docs/_build/html && python -m http.server`` and visiting ``http://localhost:8000``.
+
 Styles
 ^^^^^^
 
@@ -204,8 +207,8 @@ It divides docs into four clear areas:
 The `Django docs <https://docs.djangoproject.com/en/dev/#how-the-documentation-is-organized>`_
 also follow this system.
 
-Help
-----
+Other Tips & Tricks
+-------------------
 
 Helpful links:
 
@@ -223,6 +226,21 @@ Debugging cross-references:
 Also make sure you have used ``:ref:`` or ``:doc``
 correctly and not confused the two.
 
+Automatic rebuilds
+^^^^^^^^^^^^^^^^^^
+
+For easier docs development through file watching, automatic rebuilding and
+refreshing the browser, use `sphinx-autobuild`_:
+
+.. code-block:: console
+
+   (.venv) $ pip install sphinx-autobuild
+   (.venv) $ sphinx-autobuild -b dirhtml docs/ docs/_build/html
+
+Then visit ``localhost:8000``
+
+.. _sphinx-autobuild: https://github.com/executablebooks/sphinx-autobuild
+
 
 .. attention::
 

docs/docs/reference/installation.rst

@@ -1,6 +1,5 @@
-############
 Installation
-############
+============
 
 Isso is a web application written in Python. If pip and virtualenv mean anything
 to you, continue with :ref:`install-from-pypi`. If you are running

docs/docs/reference/multi-site-sub-uri.rst

@@ -1,6 +1,5 @@
-########################
 Multiple Sites & Sub-URI
-########################
+========================
 
 .. todo::
    Once Isso has settled on a sensible multi-site configuration which preserves

docs/docs/technical-docs/client.rst

@@ -1,6 +1,5 @@
-###############################
 Technical Documentation: Client
-###############################
+===============================
 
 .. attention::
 

docs/docs/technical-docs/server.rst

@@ -1,6 +1,5 @@
-###############################
 Technical Documentation: Server
-###############################
+===============================
 
 Dependencies
 ------------

docs/docs/technical-docs/testing-client.rst

@@ -1,6 +1,5 @@
-##################
 Testing the Client
-##################
+==================
 
 The Javascript client part of Isso is tested by the
 `Jest testing framework <https://jestjs.io/>`_.

docs/docs/technical-docs/testing-server.rst

@@ -1,22 +1,21 @@
-##################
 Testing the Server
-##################
+==================
 
 The server part of Isso is tested by the `pytest`_ tool. You should also
 install the `coverage`_ module with the `pytest-cov`_ plugin to receive code
 coverage statistics.
 
-.. code-block:: bash
+.. code-block:: console
 
-    $ pip install pytest pytest-cov coverage
+    (.venv) $ pip install pytest pytest-cov coverage
 
 Run Isso's standard server **test suite**:
 
-.. code-block:: bash
+.. code-block:: console
 
-    make tests
+    (.venv) make tests
 
-You can also run tests independently via ``pytest [options] isso/``.
+You can also run tests independently via ``pytest [options] isso/tests/``.
 
 .. note::
    Improvements to Isso's test coverage and/or different testing strategies are
@@ -25,15 +24,16 @@ You can also run tests independently via ``pytest [options] isso/``.
 
 **Check Python code style** using ``flake8``:
 
-.. code-block:: bash
+.. code-block:: console
 
-    make flakes
+    (.venv) $ pip install flake8
+    (.venv) $ make flakes
 
 Generate and view server **test coverage**:
 
-.. code-block:: bash
+.. code-block:: console
 
-    make coverage
+    (.venv) $ make coverage
 
 .. note::
    The Continuous Integration suite running via
@@ -45,19 +45,24 @@ Generate and view server **test coverage**:
 DistributionNotFound error
 --------------------------
 
-Pytest needs your Isso package to be installed as a site package to work, else it
+Pytest needs your Isso package to be visible in its ``PATH`` to work, else it
 will complain with:
 
-.. code-block:: sh
+.. code-block:: console
 
     pkg_resources.DistributionNotFound: The 'isso' distribution was not found and is required by the application
 
-When running Isso via ``pytest``, you need to be aware that it will use the
-packaged version of Isso in your ``site-packages``, not the one you have in
+When running ``pytest`` directly, you need to be aware that it will prioritize
+the packaged version of Isso in your ``site-packages``, not the one you have in
 your current working directory.
 
-Use ``pip install -e .`` to install Isso as an "editable" package (the package
-in ``site-packages`` will be a symlink to your current development directory).
+That is why you should uninstall the ``pip`` package of Isso and set
+``PYTHONPATH=.`` before running tests. The project ``Makefile`` already does
+the latter for you.
+
+Alternatively, use ``pip install -e .`` to install Isso as an "editable"
+package (the package in ``site-packages`` will be a symlink to your current
+development directory).
 
 .. _pytest: https://docs.pytest.org/
 .. _pytest-cov: https://github.com/pytest-dev/pytest-cov

docs/docs/technical-docs/testing.rst

@@ -1,6 +1,5 @@
-#####################
 Development & Testing
-#####################
+=====================
 
 Before submitting a change, you need to verify that it does not inadvertently
 break any existing functionality in Isso.