docs: Fix autodoc generation problem for deposit module
AbandonedPublic
Actions

Authored by ardumont on Sep 27 2018, 11:55 AM.

Details

Reviewers

anlambert
zack

Summary

autodoc tries to import discovered modules independently from their
runtime use.

As swh/deposit/settings holds multiple runtime settings (including
production), this wrongly tries to load the production one.

This fixes the global html documentation generation.

Related T1182

Diff Detail

Repository

rDDOC Development documentation

Branch

master

Lint

No Linters Available

Unit

No Unit Test Coverage

Build Status

Buildable 1452
Build 1796: arc lint + arc unit

Event Timeline

ardumont created this revision.Sep 27 2018, 11:55 AM

Harbormaster completed remote builds in B1452: Diff 1371.Sep 27 2018, 11:55 AM

ardumont added reviewers: anlambert, zack.Sep 27 2018, 12:09 PM

ardumont added a project: Documentation.

ardumont added a subscriber: seirl.

The issue here comes from the sphinx-apidoc tool that will generate documentation stubs for all sub-modules of swh-deposit.
Fortunately, sub-modules to exclude can be provided as parameter to the command.

In the Makefile.sphinx file from swh-docs, there is a APIDOC_EXCLUDES variable (https://forge.softwareheritage.org/source/swh-docs/browse/master/Makefile.sphinx$13)
used to declare the modules to exclude when running sphinx-apidoc. This Makefile.sphinx is then imported in the Makefile located in the docs folder of each swh module.
Good news is that you can append new modules to exclude in the APIDOC_EXCLUDES variable here.

So instead of modifying the conf.py of swh-docs, I would rather modify the doc Makefile of swh-deposit the following way:

include ../../swh-docs/Makefile.sphinx

APIDOC_EXCLUDES += ../swh/*/settings/*

So there is no need to mock swh.deposit.settings anymore as it will not end in the rst files
generated by sphinx-apidoc. The mock can also be removed in https://forge.softwareheritage.org/source/swh-deposit/browse/master/docs/conf.py.