Fix sphinx documentation build
ClosedPublic
Actions

Authored by anlambert on Jan 20 2020, 11:31 AM.

Details

Reviewers

ardumont

Group Reviewers

Reviewers

Commits

rDDOC48d36fcf8c15: docs: Fix sphinx warnings
rDDOCa6affb784656: sphinx/conf.py: Fix path to swh logo
rDDOCf425c20e4011: docs/Makefile: Exclude some modules from apidoc
rDDOCd7bb5b4253e2: requirements-swh-dev.txt: Update and reorder dependencies

Summary

The four commits in that diff fix the swh development documentation build (no more sphinx warnings).

Below is the commit log:

commit 316d17ba2d5d90a7bac30a13dd2912fcbd5d4e81 (HEAD -> fix-sphinx-dev-doc-build)
Author: Antoine Lambert <antoine.lambert@inria.fr>
Date:   Mon Jan 20 11:14:44 2020 +0100

    docs: Fix sphinx warnings
    
    Notably remove references to old swh loader modules and add docs
    for swh-search and swh-icinga-plugins.
    
    Related to T2188

commit a6affb78465697c69dbf6ecb5945e08578adf37f
Author: Antoine Lambert <antoine.lambert@inria.fr>
Date:   Mon Jan 20 11:12:15 2020 +0100

    sphinx/conf.py: Fix path to swh logo
    
    Related to T2188

commit f425c20e4011fb776e1d39637b1c70259f4f2cbd
Author: Antoine Lambert <antoine.lambert@inria.fr>
Date:   Mon Jan 20 11:10:34 2020 +0100

    docs/Makefile: Exclude some modules from apidoc
    
    Django settings modules and swh-dataset does not contain any relevant API
    documentation and apidoc generates errors and warnings while processing
    them.
    
    Related to T2188

commit d7bb5b4253e2185949596e5c8536e32daa143d2b
Author: Antoine Lambert <antoine.lambert@inria.fr>
Date:   Mon Jan 20 11:20:51 2020 +0100

    requirements-swh-dev.txt: Update and reorder dependencies
    
    Add swh-search and swh-icinga-plugins.
    
    Dependencies need to be ordered in a way that ensure only development versions
    will be used (not the release ones hosted on PyPI).
    
    Related to T2188

Diff Detail

Repository

rDDOC Development documentation

Lint

Automatic diff as part of commit; lint not applicable.

Unit

Automatic diff as part of commit; unit tests not applicable.

Event Timeline

anlambert created this revision.Jan 20 2020, 11:31 AM

Herald added a reviewer: Reviewers. · View Herald TranscriptJan 20 2020, 11:31 AM

Harbormaster completed remote builds in B10221: Diff 9154.Jan 20 2020, 11:31 AM

I dont think swh-search and swh-icinga-plugins should be linked from the main doc, as they still have the default template documentation

In D2564#60908, @vlorentz wrote:

I dont think swh-search and swh-icinga-plugins should be linked from the main doc, as they still have the default template documentation

Ack, but if we remove their inclusion the following warnings are issued and the build will fail on Jenkins:

/home/antoine/swh/swh-environment/swh-docs/docs/swh-icinga-plugins/index.rst: WARNING: document isn't included in any toctree
/home/antoine/swh/swh-environment/swh-docs/docs/swh-search/index.rst: WARNING: document isn't included in any toctree

So I will add those files to the exclude_patterns option in conf.py

Update:

do not link to swh-search and swh-icinga-plugins doc in the root index.rst file.
exclude processing of index.rst files for swh-search and swh-icinga-plugins to avoid sphinx warnings