Ensure documentation building process does not generates any rst syntax warning

mentioned in merge request !12 (closed)

mentioned in merge request swh-core!23 (closed)

mentioned in merge request swh-web!991 (closed)

added Documentation label

added priority:High label

assigned to @douardda

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.