• 
      

    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:
    Completed
    Change Summary:
    Pushed to release-5.0.x (779725a)