Page MenuHomeSoftware Heritage

Ensure documentation building process does not generates any rst syntax warning
Open, HighPublic

Related Objects

Mentioned In
rDCIDXad7b3608b3f9: Fix docstrings for 1/ rst errors and 2/ inconsistent Google style docstrings
rDWAPPSb4d298b2194f: docs: fix the index to use a proper sphinx ref to the routing table
D729: docs: fix the index to use a proper sphinx ref to the routing table
rDDOC0e0c85487798: tox: add a sphinx-dev tox environment
rDDOC891ad17c1a1c: make-doc: refactor doc build system to build the doc as a whole
rDWAPPSda8a25a9f3f8: doc: update index to match new swh-doc format
rDVAUc9e0f9dc7989: doc: update index to match new swh-doc format
rDSTOe8940643a357: doc: update index to match new swh-doc format
rDSCHcea1aed58db9: doc: update index to match new swh-doc format
rDOBJS5e7f7defd44f: doc: update index to match new swh-doc format
rDMODb8fadd11febd: doc: update index to match new swh-doc format
rDMIRFOR03cdce579851: doc: update index to match new swh-doc format
rDLDTARaec374835608: doc: update index to match new swh-doc format
rDLDSVN4f25e98e56be: doc: update index to match new swh-doc format
rDLDPYb30fae3c9534: doc: update index to match new swh-doc format
rDLDHGfb5fe5ac6a5e: doc: update index to match new swh-doc format
rDLDGd5df3bfcce8b: doc: update index to match new swh-doc format
rDLDDEB88d5b7d7a6ee: doc: update index to match new swh-doc format
rDLDDIRf12ef257a9ac: doc: update index to match new swh-doc format
rDLDBASEc321849faf26: doc: update index to match new swh-doc format
rDLSda4eb6cd348a: doc: update index to match new swh-doc format
rDJNL68b3ed6a0675: doc: update index to match new swh-doc format
rDCIDXef73ab064bcc: doc: update index to match new swh-doc format
rDDEP6ffe923eaa9c: doc: update index to match new swh-doc format
rDARC68e5182e1922: doc: update index to match new swh-doc format
rDCORE736ebc105092: doc: update index to match new swh-doc format
D697: doc: update index to match new swh-doc format
D696: make-doc: refactor doc build system to build the doc as a whole

Event Timeline

douardda created this task.Tue, Nov 13, 3:26 PM
douardda triaged this task as High priority.Tue, Nov 13, 3:58 PM
douardda claimed this task.

A first attempt to fix this task has failed. Way too naive.

The problem comes from several intricated points:

  • the fact that each swh package has its own sphinx project for the doc, but we want to build them as one (using the swh-doc sphinx 'meta' project),
  • the fact that some swh sphinx projects can not be built standalone without error/warning (caused by 'external' references),
  • the fact that we still want to generate per-package indexes (genindex and py-modindex).

The build process for now is to build each and every swh package as a standalone project, which generates warning and error since it may have references to other swh packages but generates assets and 'local' indexes (and modify them via a bunch of sed to fix paths), then build the swh-doc project, which will recompile all the rst files, this time (hopefully) without errors.

So each rst file is compiled twice in this process.

In my naive attempt, I did fix one aspect (building assets) but I missed the local indexes generation.

Now I'm not sure what's the best approach for this documentation building process. This whole dual-mode build (local in each swh package then global in swh-doc) has a few quirks and seems a bit fragile and hackish.

But I'm not sure how we can improve/simplify it. My feeling is that it would be better to have each swh package sphinx project built independently (using the extlinks extension) and keep the swh-doc for the narrative documentation with references to each swh package.

zack added a subscriber: zack.Mon, Nov 19, 1:08 PM

Would removing your 3rd requirement (per-package indexes) simplify things? I don't see that as a goal at all, just what happens by default with the minimalistic sphinx setup we used back in the days. I'd be much happier if we could have a single index / navigation bar, where the doc of all modules appear.