Document installation and basic configuration

docs/source/index.rst

@@ -4,14 +4,49 @@
 Sphinx Testify
 ##############
 
-``Testify`` is an extension to Sphinx which enables
-writing `TODO: testified documentation <http://example.com>`_.
+``sphinx-testify`` is an extension to Sphinx which allows
+testifying documentation: ensuring that it is also up-to-date an
+aligned with the library or application capabilities.
+
+`TODO: testified documentation <http://example.com>`_.
 
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+Installation
+============
+
+We support Python version TODO and newer.
+However, we support only the latest versions of Sphinx.
+
+To install, run
+
+.. code-block:: shell
+
+   pip install sphinx-testify
+
+Basic configuration
+===================
+
+.. testify::
+
+   pytest.tests.test_sphinx_testify.test_basic_configuration
+
+To enable ``sphinx-testify``, add it to the list of extensions in Sphinx project
+``conf.py`` and add a path to jUnit XML -formatted tests result file. For example:
+
+.. code-block:: python
+
+   extensions = [
+       'sphinx_testify'
+   ]
+
+   testify_from = [
+       '/path/to/test_results.xml'
+   ]
+
 
 ``Testify`` provides a Sphinx directive, which verifies
 whether the given unit tests succeeded and fails the documentation build

tests/conftest.py

@@ -4,13 +4,17 @@
 
 from __future__ import annotations
 
+import logging
+
 from pathlib import Path
 
 import pytest
 from sphinx.testing.util import SphinxTestApp
-
+from sphinx.errors import ExtensionError
 from sphinx_testify.test_result import TestResult
 
+log = logging.getLogger(__file__)
+
 pytest_plugins = ('sphinx.testing.fixtures',)
 
 # Exclude 'fixtures' dirs for pytest test collector
@@ -35,7 +39,13 @@ class TestifySphinxTestApp:
     def __init__(self, app: SphinxTestApp):
         self._app = app
         self._testified = []
-        self._app.connect('testify-testified', self._on_testified)
+        try:
+            self._app.connect('testify-testified', self._on_testified)
+        except ExtensionError:
+            log.warning(
+                "Unable to listen to `testify-testified` event. "
+                "NOTE: This might be intentional."
+            )
 
     def _on_testified(self, _app, test_result: TestResult):
         self._testified.append(test_result.name)

tests/fixtures/test-basic-configuration/conf.py

@@ -0,0 +1,9 @@
+import os
+
+extensions = [
+    'sphinx_testify'
+]
+
+testify_from = [
+    os.path.dirname(__file__) + '/test_results.xml'
+]

tests/fixtures/test-basic-configuration/index.rst

@@ -0,0 +1,2 @@
+Test basic configuration
+########################

tests/fixtures/test-basic-configuration/test_results.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<testsuites>
+  <testsuite name="nomatter">
+    <testcase classname="nomatter" name="nomatter" />
+  </testsuite>
+</testsuites>

tests/test_sphinx_testify.py

@@ -8,6 +8,11 @@
 from .conftest import TestifySphinxTestApp
 
 
+@pytest.mark.sphinx('html', testroot='basic-configuration')
+def test_basic_configuration(test_app: TestifySphinxTestApp):
+    test_app.build()
+
+
 @pytest.mark.sphinx('html', testroot='single-passed-test')
 def test_testify_single_passed_test_case(test_app: TestifySphinxTestApp):
     test_app.build()