I noticed that the faro documentation is structured differently from the rest of the PIpelines documentation. I suggest that we make some changes for the sake of consistency and usability in our docs.

The key issue is that there are Python module documentation directories for lsst.faro itself as well as faro's individual sub-packages: lsst.faro.base, lsst.faro.measurement, lsst.faro.preparation, lsst.faro.summary, and lsst.faro.utils.

The index.rst page lsst.faro is listing the API for all sub-packages, and the pages for each sub-package are also listing their own Python APIs. This creates a situation where there are multiple homepages for the same thing and it's not clear whether to find APIs, tasks, and narrative docs.

(Faro is using a mechanism whereby a single EUPS package can have documentation for multiple Python packages. This mechanism was created for afw to deal with its mash of distinct Python packages contained in a single EUPS package. Because the faro is a cohesive package, I don't think it makes sense for its to have distinct homepages for different parts and the overall package).

My suggestion is to merge all documentation content into lsst.faro, which would be consistent with the documentation design guidelines.

If your concern is that you want distinct listings of tasks for measurement, versus preparation, and summary, keep in mind that you can create user guide pages (Under the "Using lsst.faro" heading) with lists of tasks as well as any tutorial/guide content). To do this, you can use the .. lsst-tasks:: directive, using a root specific to that sub-package, and being sure to omit the toctree option. For more docs, see ¶https://documenteer.lsst.io/sphinx-extensions/lssttasks.html#directive-lsst-tasks

In addition to this, the documentation pages are missing headlines and other parts of their structure. You might keep this in mind when merging the documentation pages together:

• lsst.faro.base, measurement, preparation, summary  is missing the headline "Task reference" and also lacks an introductory description.
• utils is missing an introductory paragraph

See https://developer.lsst.io/stack/module-homepage-topic-type.html for more info.