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)