Fix several issues in our Sphinx extension for webapi documentation.

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

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.

Summary ID
Fix several issues in our Sphinx extension for webapi documentation.
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.
64d17ca2b248d92dbb409cdea3759e3ff195b46c
david
  1. Ship It!
  2. 
      
chipx86
Review request changed

Status: Closed (submitted)

Change Summary:

Pushed to release-5.0.x (779725a)
Loading...