docs: fix sphinx warnings

This patch fixes all sphinx warnings and also changes sphinx building to
treat warnings as errors so that we don't introduce new warnings.

Also:
- ci: fail on sphinx warnings.
- ci: don't use GitHub actions to build docs as this is being done by
  readthedocs.org.
- build: supress "more than one target found for cross-reference"
  warnings from sphinx autodoc.

Author: aucampia

.github/workflows/validate.yaml

@@ -104,37 +104,3 @@ jobs:
           export TOXENV
           export TOX_EXTRA_COMMAND="${{ matrix.TOX_EXTRA_COMMAND }}"
           "${test_harness[@]}" python -m tox
-  docs:
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        tox-env: ["docs"]
-    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: tox-${{ matrix.tox-env }}-pip-v1-${{
-            hashFiles('**/setup.py', '**/requirements*.txt') }}
-          restore-keys: |
-            tox-${{ matrix.tox-env }}-pip-v1-
-      - name: Install dependencies
-        shell: bash
-        run: |
-          python -m pip install tox tox-gh-actions
-      - name: Run ${{ matrix.tox-env }}
-        shell: bash
-        run: |
-          python -m tox -e ${{ matrix.tox-env }}

.readthedocs.yaml

@@ -14,3 +14,6 @@ python:
       path: .
       extra_requirements:
         - docs
+
+sphinx:
+  fail_on_warning: true

docs/conf.py

@@ -243,3 +243,9 @@ def find_version(filename):
 html_experimental_html5_writer = True
 
 needs_sphinx = "4.1.2"
+
+suppress_warnings = [
+    # This is here to prevent:
+    #  "WARNING: more than one target found for cross-reference"
+    "ref.python",
+]

docs/developers.rst

@@ -38,7 +38,7 @@ met:
 
   There should either be existing tests that cover the changed code and
   behaviour, or the PR should include tests. For more information about what is
-  considered adequate testing see the :ref:`Tests section <Tests>`.
+  considered adequate testing see the :ref:`Tests section <tests>`.
 
 * Documentation that covers something that changed has been updated.
 
@@ -65,7 +65,7 @@ the users of this project.
 Please note that while we would like all PRs to follow the guidelines given
 here, we will not reject a PR just because it does not.
 
-.. Tests:
+.. _tests:
 
 Tests
 -----

docs/rdf_terms.rst

@@ -13,64 +13,64 @@ All terms in RDFLib are sub-classes of the :class:`rdflib.term.Identifier` class
    :caption: Term Class Hierarchy
    :type: plantuml
 
-@startuml
-skinparam shadowing false
-skinparam monochrome true
-skinparam packageStyle rectangle
-skinparam backgroundColor FFFFFE
-
-class Node
-
-class Identifier {
-    eq(other) -> bool
-    neq(other) -> bool
-    startswith(prefix: str, start, end) -> bool
-}
-Identifier -up-|> Node
-
-class IdentifiedNode {
-    toPython() -> str
-}
-IdentifiedNode -up-|> Identifier
-
-class URIRef {
-    n3(namespace_manager) -> str
-    defrag() -> URIRef
-    de_skolemize() -> BNode
-}
-URIRef -up-|> IdentifiedNode
-
-
-class Genid
-Genid -up-|> URIRef
-
-class RDFLibGenid
-RDFLibGenid -up-|> Genid
-
-class BNode {
-    n3(namespace_manager) -> str
-    skolemize(authority, basepath) -> RDFLibGenid
-}
-BNode -up-|> IdentifiedNode
-
-class Literal {
-    datatype: Optional[str]
-    lang: Optional[str]
-    value: Any
-
-    normalize() -> Literal
-    n3(namespace_manager) -> str
-    toPython() -> str
-}
-Literal -up-|> Identifier
-
-class Variable {
-    n3(namespace_manager) -> str
-    toPython() -> str
-}
-Variable -up-|> Identifier
-
-@enduml
+    @startuml
+    skinparam shadowing false
+    skinparam monochrome true
+    skinparam packageStyle rectangle
+    skinparam backgroundColor FFFFFE
+    
+    class Node
+    
+    class Identifier {
+        eq(other) -> bool
+        neq(other) -> bool
+        startswith(prefix: str, start, end) -> bool
+    }
+    Identifier -up-|> Node
+    
+    class IdentifiedNode {
+        toPython() -> str
+    }
+    IdentifiedNode -up-|> Identifier
+    
+    class URIRef {
+        n3(namespace_manager) -> str
+        defrag() -> URIRef
+        de_skolemize() -> BNode
+    }
+    URIRef -up-|> IdentifiedNode
+    
+    
+    class Genid
+    Genid -up-|> URIRef
+    
+    class RDFLibGenid
+    RDFLibGenid -up-|> Genid
+    
+    class BNode {
+        n3(namespace_manager) -> str
+        skolemize(authority, basepath) -> RDFLibGenid
+    }
+    BNode -up-|> IdentifiedNode
+    
+    class Literal {
+        datatype: Optional[str]
+        lang: Optional[str]
+        value: Any
+    
+        normalize() -> Literal
+        n3(namespace_manager) -> str
+        toPython() -> str
+    }
+    Literal -up-|> Identifier
+    
+    class Variable {
+        n3(namespace_manager) -> str
+        toPython() -> str
+    }
+    Variable -up-|> Identifier
+    
+    @enduml
 
 Nodes are a subset of the Terms that the underlying store actually persists.
 The set of such Terms depends on whether or not the store is formula-aware. 

tox.ini

@@ -34,7 +34,7 @@ passenv = TERM
 setenv =
     PYTHONHASHSEED = 0
 commands =
-    sphinx-build -n -T -b html -d {envdir}/doctree docs docs/_build/html
+    sphinx-build -n -T -W -b html -d {envdir}/doctree docs docs/_build/html
 
 [testenv:precommit{,all}]
 skip_install = true