We auto-generate our API documentation, and the rendered output for this
hasn't changed much since the beginning. However, it wasn't very good in
many ways. In particular, resource fields were cramped and especially
hard to read on mobile, and the list of errors for resources really
didn't tell you much. We also couldn't easily make use of the same field
listings inside of docstrings (which impacted the FileDiff resource).
This change redoes the output for these parts of the API doc generator.
It splits up the main resource directive a bit, creating a new field
directive and field list directive.
The field directive renders information on a single field (name, type,
description, requirement state, and versioning information). This is
used by the doc generator and can also be used by docstrings.
The field list directive renders a list of fields, and again can be used
not just by the doc generator but also by docstrings.
The output for fields has changed to be easier to digest with plenty of
room for content. Instead of a 3 column table with headers, we now have
2 columns, one that shows the name and type, and one that shows the rest
of the information. The look is much cleaner (with some upcoming changes
to the website), and does a much better job of highlighting required
fields and deprecated fields.
The error list also shows some additional information now. It not only
lists the API error, but also the HTTP error code and a description of
the error, preventing having to click through to get any details.
The error page no longer shows sample XML payloads. We haven't shown XML
for resource payloads in a while.
The result of all this is a much nicer, mobile-friendly way of seeing
details on the API without having to stretch your browser window. Field
descriptions can be more informative and contain much more information
than before, and users don't have to click around as much to get useful
information.
Testing Done:
Went through every doc page and tested every capability of the fields
and errors display (versioning information, required vs. optional,
complex content, etc.).
Reviewed at https://reviews.reviewboard.org/r/8775/