From 8c65e6c19802a916e3d49761e9a3c10db36a48d6 Mon Sep 17 00:00:00 2001 From: Iwan Aucamp Date: Thu, 14 Apr 2022 23:04:19 +0200 Subject: [PATCH] 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. --- .github/workflows/validate.yaml | 34 ---------- .readthedocs.yaml | 3 + docs/conf.py | 6 ++ docs/developers.rst | 4 +- docs/rdf_terms.rst | 116 ++++++++++++++++---------------- tox.ini | 2 +- 6 files changed, 70 insertions(+), 95 deletions(-) diff --git a/.github/workflows/validate.yaml b/.github/workflows/validate.yaml index 68a157220..83ecc7985 100644 --- a/.github/workflows/validate.yaml +++ b/.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 }} diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 6c6e4c6f3..e19735429 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -14,3 +14,6 @@ python: path: . extra_requirements: - docs + +sphinx: + fail_on_warning: true diff --git a/docs/conf.py b/docs/conf.py index ecd43e177..c0f0d68f9 100644 --- a/docs/conf.py +++ b/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", +] diff --git a/docs/developers.rst b/docs/developers.rst index b716adc7b..0df461513 100644 --- a/docs/developers.rst +++ b/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 `. + considered adequate testing see the :ref:`Tests section `. * 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 ----- diff --git a/docs/rdf_terms.rst b/docs/rdf_terms.rst index a96823258..cc880a02f 100644 --- a/docs/rdf_terms.rst +++ b/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. diff --git a/tox.ini b/tox.ini index 35dec2d73..ed540e941 100644 --- a/tox.ini +++ b/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