API Documentation

[Rachel-Reverie]

Hi everyone!

We're working on getting our Public API documented and added to the "Reference" category of our online docs. Part of that is deciding on a format and layout for the new documentation, as well as how it will be organized and displayed for perusal (index pages, table of contents, etc.) In the interests of making our docs as useful and user-friendly as possible, I'm here to ask for good examples of API documentation and organization which we can reference when while building our own.

So: What existing documentation for Python modules/APIs do you find easiest to work with? And are there any features that you would particularly like to see when our API docs go live?

As always, thanks for your input and feedback!

[AlbertUlysses]

Hi!
The simple ones with examples are usually the best when it comes to API docs.
For example, the Star War's API is pretty decent. I wouldn't say the design style is excellent, but the content is good.

The one complaint I have about some API docs, including the Star Wars example, is that they tend only to be one long page, making it a pain to navigate.

Star Wars API link:
https://swapi.dev/documentation

[Rachel-Reverie]

Thanks for that feedback. I'm currently working on a design where each method has it's own dedicated page (grouped under a class category if they share class membership) so I can promise you won't have to wade through a single massive API doc.

Currently we're generating the API docs by parsing the relevant docstrings and running inspections on the module/class/method in question, so each page should be pretty simple and straight forward: There will be a synopsis followed by links to the pages for associated methods (if the object is a class) or a table with the parameters (if the object being documented is a method). The table will detail a parameter's name, type signature, default value (if any), and a description pulled from the docstring. After that there will be a section for details on what the method returns, followed by a section for potentially raised expectations, and finally links to related how-to guides and documentation (which should contain the examples you want).

However, I'll push to have our docstrings standardized to include an example usage so we can include that on the API page as well.

Thanks again!