Compile docs in GitHub Actions CI

This is to make sure that there are no doc build failures introduced by
PRs.

In future I want to expand this check to be more strict. Since it comes up
separately in CI it can be ignored on reviwer discrescion but at least
it will make problems visible.

Also:
- Fix some things in docs that were causing warnings. There are still
  many warnings related to references but I will fix them later.
- Added a `docs` evnrionment for tox which builds the docs, this is also
  what is used from CI.

6 files changed, 63 insertions, 19 deletions

diff --git a/.github/workflows/validate.yaml b/.github/workflows/validate.yaml
index bbc09fb1..2a7150b9 100644
--- a/.github/workflows/validate.yaml
+++ b/.github/workflows/validate.yaml
@@ -9,6 +9,7 @@ on:
 env:
   FORCE_COLOR: 1
   XDG_CACHE_HOME: ${{ github.workspace }}/cache
+  DEFAULT_PYTHON: "3.7"
 
 jobs:
   validate:
@@ -90,3 +91,33 @@ jobs:
           flake8 --exit-zero rdflib
           mypy --show-error-context --show-error-codes
           "${test_harness[@]}" pytest -ra --cov
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{env.DEFAULT_PYTHON}}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{env.DEFAULT_PYTHON}}
+      - name: Get pip cache dir
+        id: pip-cache
+        shell: bash
+        run: |
+          python -m ensurepip --upgrade
+          echo "::set-output name=dir::$(pip cache dir)"
+      - name: Cache pip
+        uses: actions/cache@v2
+        with:
+          path: ${{ steps.pip-cache.outputs.dir }}
+          key: docs-pip-v1-${{
+            hashFiles('**/setup.py', '**/requirements*.txt') }}
+          restore-keys: |
+            docs-pip-v1-
+      - name: Install dependencies
+        shell: bash
+        run: |
+          python -m pip install tox
+      - name: Build docs
+        shell: bash
+        run: |
+          python -m tox -e docs
diff --git a/docs/developers.rst b/docs/developers.rst
index be6bb94a..59d41883 100644
--- a/docs/developers.rst
+++ b/docs/developers.rst
@@ -11,9 +11,9 @@ developing RDFLib code.
 
 * Please be as Pythonic as possible (:pep:`8`).
 * Code should be formatted using `black <https://github.com/psf/black>`_
-and we use Black v21.9b0, with the black.toml config file provided.
+  and we use Black v21.9b0, with the black.toml config file provided.
 * Code should also pass `flake8 <https://github.com/psf/black>`_ linting
-and `mypy <http://mypy-lang.org/>`_ type checking.
+  and `mypy <http://mypy-lang.org/>`_ type checking.
 * You must supply tests for new code
 
 If you add a new cool feature, consider also adding an example in ``./examples``
diff --git a/docs/intro_to_parsing.rst b/docs/intro_to_parsing.rst
index b74793a9..4593aa7d 100644
--- a/docs/intro_to_parsing.rst
+++ b/docs/intro_to_parsing.rst
@@ -104,13 +104,13 @@ The following table lists the RDF formats you can serialize data to with rdflib,
 
    "Turtle",    "turtle, ttl or turtle2",     "turtle2 is just turtle with more spacing & linebreaks"
    "RDF/XML",   "xml or pretty-xml",     "Was the default format, rdflib < 6.0.0"
-   "JSON-LD",   "json-ld",     "There are further options for compact syntax and other JSON-LD variants"   
+   "JSON-LD",   "json-ld",     "There are further options for compact syntax and other JSON-LD variants"
    "N-Triples", "ntriples, nt or nt11",     "nt11 is exactly like nt, only utf8 encoded"
    "Notation-3","n3",     "N3 is a superset of Turtle that also caters for rules and a few other things"
-   
-    "Trig",     "trig",     "Turtle-like format for RDF triples + context (RDF quads) and thus multiple graphs"
-    "Trix",     "trix",     "RDF/XML-like format for RDF quads"
-"N-Quads",   "nquads",     "N-Triples-like format for RDF quads"
+
+   "Trig",     "trig",     "Turtle-like format for RDF triples + context (RDF quads) and thus multiple graphs"
+   "Trix",     "trix",     "RDF/XML-like format for RDF quads"
+   "N-Quads",   "nquads",     "N-Triples-like format for RDF quads"
 
 Working with multi-graphs
 -------------------------
diff --git a/rdflib/namespace/__init__.py b/rdflib/namespace/__init__.py
index dcedd170..bbe88981 100644
--- a/rdflib/namespace/__init__.py
+++ b/rdflib/namespace/__init__.py
@@ -74,6 +74,7 @@ The following namespaces are available by directly importing from rdflib:
 * XSD
 
 .. code-block:: pycon
+
     >>> from rdflib.namespace import RDFS
     >>> RDFS.seeAlso
     rdflib.term.URIRef('http://www.w3.org/2000/01/rdf-schema#seeAlso')
diff --git a/rdflib/plugins/stores/sparqlstore.py b/rdflib/plugins/stores/sparqlstore.py
index aed43088..35fabf02 100644
--- a/rdflib/plugins/stores/sparqlstore.py
+++ b/rdflib/plugins/stores/sparqlstore.py
@@ -208,6 +208,7 @@ class SPARQLStore(SPARQLConnector, Store):  # type: ignore[misc]
 
         **context** may include three parameter
         to refine the underlying query:
+
         * LIMIT: an integer to limit the number of results
         * OFFSET: an integer to enable paging of results
         * ORDERBY: an instance of Variable('s'), Variable('o') or Variable('p') or, by default, the first 'None' from the given triple
@@ -219,17 +220,15 @@ class SPARQLStore(SPARQLConnector, Store):  # type: ignore[misc]
               the walking path on the graph)
             - Using OFFSET without defining LIMIT will discard the first OFFSET - 1 results
 
-        ``
-        a_graph.LIMIT = limit
-        a_graph.OFFSET = offset
-        triple_generator = a_graph.triples(mytriple):
-          # do something
-          # Removes LIMIT and OFFSET if not required for the next triple() calls
-        del a_graph.LIMIT
-        del a_graph.OFFSET
-        ``
-
+        .. code-block:: python
 
+            a_graph.LIMIT = limit
+            a_graph.OFFSET = offset
+            triple_generator = a_graph.triples(mytriple):
+            # do something
+            # Removes LIMIT and OFFSET if not required for the next triple() calls
+            del a_graph.LIMIT
+            del a_graph.OFFSET
         """
 
         s, p, o = spo
@@ -536,9 +535,9 @@ class SPARQLUpdateStore(SPARQLStore):
         self._updates = 0
 
     def open(self, configuration: Union[str, Tuple[str, str]], create=False):
-        """This method is included so that calls to this Store via Graph, e.g.
+        """
+        This method is included so that calls to this Store via Graph, e.g.
         Graph("SPARQLStore"), can set the required parameters
-
         """
         if type(configuration) == str:
             self.query_endpoint = configuration  # type: ignore[assignment]
@@ -575,6 +574,7 @@ class SPARQLUpdateStore(SPARQLStore):
     def open(self, configuration, create=False):  # type: ignore[no-redef]
         """
         sets the endpoint URLs for this SPARQLStore
+
         :param configuration: either a tuple of (query_endpoint, update_endpoint),
             or a string with the endpoint which is configured as query and update endpoint
         :param create: if True an exception is thrown.
diff --git a/tox.ini b/tox.ini
index b3076fcc..c09483da 100644
--- a/tox.ini
+++ b/tox.ini
@@ -33,3 +33,15 @@ commands =
 deps =
 	-rrequirements.txt
 	-rrequirements.dev.txt
+
+[testenv:docs]
+basepython =
+    python3.7
+deps =
+extras =
+    docs
+passenv = TERM
+setenv =
+    PYTHONHASHSEED = 0
+commands =
+    sphinx-build -n -T -b html -d {envtmpdir}/doctrees docs docs/_build/html