Page MenuHomeSoftware Heritage

sphinx/conf.py: Add standalone package doc configuration for tox build
ClosedPublic

Authored by anlambert on Wed, Apr 21, 5:14 PM.

Details

Summary

Enable to build the local documentation of each swh package using a
dedicated tox environment.

In order to check for possibly introduced sphinx warnings in the
documentation sources, the documentation is built with the -W option
of sphinx-build.

As some references located in scopes external to the processed
package would not be resolved, related sphinx warnings are
suppressed to allow the doc build to succeed anyway.

Besides the errors related to references that can only be checked
when building the full documentation, all other sphinx errors
should be caught.

Related to T3258

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

ardumont added a subscriber: ardumont.

ok, i think ;)

This revision is now accepted and ready to land.Wed, Apr 21, 6:33 PM

thx!

swh/docs/sphinx/conf.py
171

Please add a docstring/commentto explain when it is set.

And explain it in swh-docs/README.md too

267–279

shouldn't this be turned off when building swh-web's doc? (not a big deal if it isn't)

(requesting changes, so you don't accidentally merge it if you missed the notif, but I'm fine on principle)

This revision now requires changes to proceed.Thu, Apr 22, 11:21 AM

Update:

  • add comments about the SWH_PACKAGE_DOC_TOX_BUILD env variable
  • add a section in README.md explaining how to build standalong package documentation with tox
  • keep httpdomain warnings for swh-web

Also mention that warnings related to unresolved references are suppressed in README.

vlorentz added inline comments.
swh/docs/sphinx/conf.py
171–172

except the swh-docs package itself

This revision is now accepted and ready to land.Thu, Apr 22, 8:47 PM

Update:

  • Ensure swh_substitutions can be found for sphinx and sphinx-dev tox envs
  • Use sphinx-dev tox env in README

Build is green

Patch application report for D5571 (id=19970)

Rebasing onto 80832699e0...

Current branch diff-target is up to date.
Changes applied before test
commit 9ba33def779d70197d40c212d69bc363bcf0b0e8
Author: Antoine Lambert <antoine.lambert@inria.fr>
Date:   Fri Apr 16 19:06:42 2021 +0200

    tox: Add sphinx environments to check sane doc build
    
    Enable to check package documentation can be built without producing
    sphinx warnings.
    
    The sphinx environment is designed to be used in continuous integration.
    
    The sphinx-dev environment is designed to be used inside a full swh
    development environment.
    
    Related to T3258

See https://jenkins.softwareheritage.org/job/DCORE/job/tests-on-diff/216/ for more details.