RE: Add API documentation for homepage shelves #16087
Conversation
eviljeff
left a comment
There was a problem hiding this comment.
Not sure if we make this clear in our docs, but make docs locally to build the rst and be able to look at the html (the CI would pick up any syntax errors but it's nice to be able to look at the finished doc before merging to see how it reads)
docs/topics/api/shelves.rst
Outdated
| :query int count: The number of results for this query. | ||
| :query string next: The URL of the next page of results. | ||
| :query string previous: The URL of the previous page of results. | ||
| :>json array results: The array of shelves displayed on the AMO Homepage. Each shelf includes its title, url, endpoint, criteria, footer text, footer pathname, and the add-ons based on the shelf's endpoint and criteria. |
There was a problem hiding this comment.
Rather than list the fields here, we should continue with the breakdown of the data structure for the objects inside results. (The secondary hero shelf above is an example)
so for title,
:>json string results[].title: The title of the shelf.and so on for all the fields in ShelfSerializer.Meta.fields.
addons would be :>json array results[].addons: <a brief explanation of what the addons are here> Maybe link to the result documentation for the addons and collections endpoints too? Not sure if it's obvious, but rst links look like :ref:`link text <anchor-name-without-the-leading-underscore>`
|
@eviljeff, the latest push includes updates per your feedback. Please see below for a screenshot of how the finished doc would look as well.
Please review when you have a moment. Thank you! |
eviljeff
left a comment
There was a problem hiding this comment.
Happy new year! 🎉
Looks good, r+
| :>json string results[].criteria: The criteria for the addons in the shelf. | ||
| :>json string|null results[].footer_text: The optional text in the footer of the shelf. | ||
| :>json string|null results[].footer_pathname: The optional pathname of the URL for the footer's text. | ||
| :>json array results[].addons: An array of :ref:`add-ons <addon-detail-object>` or :ref:`collections <collection-detail-object>`. |
There was a problem hiding this comment.
oh, do we return the CollectionAddonSerializer data structure for collections rather than Addon? I must have missed that along the way - it should always be just the flat addon. That's something for a follow-up - the docs are correct as of now.
Fixes mozilla/addons#7964
This pull request includes the API documentation for homepage shelves within
docs/topics/api/shelves.rst.As other anchor texts either reflected the title of the section or the endpoint, I used
homepage-shelves. Please let me know if it should be revised (e.g,shelves,homepage-shelf).Please review when you have a moment. Thanks!