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.

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.

I'd like to close this task, but unfortunately:

build succeeded, 33 warnings.

(from https://jenkins.softwareheritage.org/job/DDOC/job/publish/694/console). Still needs a bit of tuning, it seems.