Fix several issues in our Sphinx extension for webapi documentation.

Review Request #12539 — Created Aug. 16, 2022 and submitted — Latest diff uploaded

Information

Review Board
release-5.0.x

Reviewers

A long while back, work was done on the webapidocs Sphinx extension to
fix how URLs were generated for example payloads. This was done in
commit 527b0c461b.

That work regressed some of the behavior, and we never caught it until
now. The paths being built didn't include all components of the path.
There were also other issues from this change, like an attempt at
raising an exception that itself could crash.

This change fixes that path building, and also fixes a couple other
issues noted in the API:

  1. The "HTTP Methods" text was no longer inlining content, causing the
    description for a method to be in its own paragraph. This is likely a
    regression due to a Sphinx or docutils change.

  2. We were showing whether resources support anonymous access, a
    holdover from a very long time ago. This was misleading at best, as
    it determines this from the usage of decorators we no longer use, and
    doesn't factor in how access control actually works. This has been
    removed.

These changes will be backported to 4.0.

Built the documentation. Checked a variety of doc pages with different
levels of URL nesting, involving lists, items, and singletons. The URLs
were all correct.

Commits

Files