DM-32820: Skip ButlerURI in table of contents

[timj]

Aliasing ButlerURI to ResourcePath works fine for code but breaks sphinx documentation building. Workaround this by removing the table of content entry.

Checklist

• ran Jenkins
• added a release note for user-visible changes to doc/changes

[codecov]

Codecov Report

Merging #613 (e3fa06e) into main (7439250) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main     #613   +/-   ##
=======================================
  Coverage   83.78%   83.78%           
=======================================
  Files         231      231           
  Lines       29616    29616           
  Branches     4910     4910           
=======================================
  Hits        24813    24813           
  Misses       3672     3672           
  Partials     1131     1131           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7439250...e3fa06e. Read the comment docs.

[timj]

@jonathansick This does work in the sense that some words appear, but it doesn't result in something that is clickable. Am I doing something wrong? The :skip: fixes the pipelines.lsst.io build problem so it's not important.

[jonathansick]

What automodapi does, once it detects the available symbols in a namespace, is create rst pages that in turn contain py:class directives and so on. Then it creates an automodsumm in place of the automodapi while creates the click-able table of contents. I'm assuming that this ButlerURI documentation in lsst.daf.butler is only temporary, so I don't think it's worth the trouble to fake the look of automodsumm.

Also note that if there are existing links in the documentation to methods of ButlerURI, you'd technically want to add those methods to your doc for ButlerURI. You'd do this by putting py:method directives inside the scope of the py:class directive. If there aren't such links, I wouldn't worry about it.

[timj]

There aren't any links to methods, just the class. The docs do build fine with this change so I'll leave it. The plan is to do a global replacement of ButlerURI with ResourcePath so I'll leave it as is and merge this to solve the immediate problem of the pipelines.lsst.io build not working.

[jonathansick]

What automodapi does, once it detects the available symbols in a namespace, is create rst pages that in turn contain py:class directives and so on. Then it creates an automodsumm in place of the automodapi while creates the click-able table of contents. I'm assuming that this ButlerURI documentation in lsst.daf.butler is only temporary, so I don't think it's worth the trouble to fake the look of automodsumm.

Also note that if there are existing links in the documentation to methods of ButlerURI, you'd technically want to add those methods to your doc for ButlerURI. You'd do this by putting py:method directives inside the scope of the py:class directive. If there aren't such links, I wouldn't worry about it.