Improve the rendered output for the API documentation.
Review Request #443 — Created March 2, 2017 and updated — Latest diff uploaded
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/