• 
      

    Give greater control over API doc input and avoid broken docs.

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

    Information

    Review Board
    release-5.0.x

    Reviewers

    Over time, the webapidocs code has changed to accommodate changes in
    our API, and so has our test data. These changes have largely been done
    without properly auditing the resulting documentation, and unfortunately
    starting in Review Board 4, we ended up with a lot of bad, mostly-empty
    payloads and broken docs due to new objects in the database for the DVCS
    work that took precedence over other curated docs. This has further
    worsened with the changes for Review Board 5.

    This change redoes a lot of how the doc generation code decides which
    objects to pick. It still has the introspection capabilities, but now
    specific docs can provide values for URLs to allow examples to be based
    on specific entries. That means we can continue to augment the
    documentation database data without further regressions.

    The 4.0 release also introduced features that the documentation is still
    saying must be turned on for use. That's very misleading. We now only
    show a notice if a feature is listed as off by default.

    Several examples with bad data would show up, and some would not. Same
    with links. We worked around this with options for the directive to turn
    these off, but with the fixes in this release, we no longer need to do
    that for most resources.

    Bad assumptions that led to hiding documentation for resources without
    models have been fixed.

    Examples now include the HTTP status code, and no longer show the wrong
    payload if the response is a redirect.

    And finally, the example URL now uses https instead of http.

    Generated the docs and carefully went through every single page. Made sure
    all URLs and examples were correct.

    This does have a counterpart involving new database data, which will go
    in separately.

    Summary ID
    Give greater control over API doc input and avoid broken docs.
    Over time, the `webapidocs` code has changed to accommodate changes in our API, and so has our test data. These changes have largely been done without properly auditing the resulting documentation, and unfortunately starting in Review Board 4, we ended up with a lot of bad, mostly-empty payloads and broken docs due to new objects in the database for the DVCS work that took precedence over other curated docs. This has further worsened with the changes for Review Board 5. This change redoes a lot of how the doc generation code decides which objects to pick. It still has the introspection capabilities, but now specific docs can provide values for URLs to allow examples to be based on specific entries. That means we can continue to augment the documentation database data without further regressions. The 4.0 release also introduced features that the documentation is still saying must be turned on for use. That's very misleading. We now only show a notice if a feature is listed as off by default. Several examples with bad data would show up, and some would not. Same with links. We worked around this with options for the directive to turn these off, but with the fixes in this release, we no longer need to do that for most resources. Bad assumptions that led to hiding documentation for resources without models have been fixed. Examples now include the HTTP status code, and no longer show the wrong payload if the response is a redirect. And finally, the example URL now uses `https` instead of `http`.
    5e8f9410d8a9759a399deec9cd2dbe3a0cf85653
    Description From Last Updated

    module level import not at top of file Column: 1 Error code: E402

    reviewbotreviewbot

    module level import not at top of file Column: 1 Error code: E402

    reviewbotreviewbot
    Checks run (1 failed, 1 succeeded)
    flake8 failed.
    JSHint passed.

    flake8

    david
    1. Ship It!
    2. 
        
    chipx86
    Review request changed
    Status:
    Completed
    Change Summary:
    Pushed to release-5.0.x (5fdd9ba)