Page MenuHomeSoftware Heritage

Fix sphinx documentation build
ClosedPublic

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

Details

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

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

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

anlambert updated this revision to Diff 9155.Jan 20 2020, 1:13 PM

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
ardumont accepted this revision.Jan 20 2020, 2:02 PM
This revision is now accepted and ready to land.Jan 20 2020, 2:02 PM