Some initial big-picture thoughts.
Determine the capabilities & correct usage of pydoc for
The pydoc CLI tool doesn't do any high-level text formatting like man does. The text in the docstring is the text it renders. Because of that, the way to get the best rendering across both pydoc and HTML documentation is to pick a plain text markup that looks good either way.
There are a few options here but I think our realistic choice is reStructuredText vs. Markdown. reST is the best-supported format for Python documentation, and it does have more directive for higher-level formatting. Markdown is of course more popular generally and we're already using it so it's one less thing for the team to learn.
For us I think I would vote Markdown, with a style guide that emphasizes plaintext readability (e.g., footnote-style links, underlined headers, etc.). But either is fine.
- annotating function parameters
The only officially supported annotations are type annotations, see below. Beyond that, there are conventions for documenting arguments in docstrings, but they're just that, conventions. Not even the official style guide PEP 257 has a suggestion. We should just settle on one and it should become part of the document.
PEP 257 does have thoughts about this. I quote:
The docstring for a module should generally list the classes, exceptions and functions (and any other objects) that are exported by the module, with a one-line summary of each. (These summaries generally give less detail than the summary line in the object’s docstring.) The docstring for a package (i.e., the docstring of the package’s __init__.py module) should also list the modules and subpackages exported by the package.
- treatment of Py3 type annotations (what does the documentation system do with them, how are they displayed, how does it take advantage of it)
pydoc will display them basically the same as they're written in the source code. So do most modern documentation publishing systems, including the one we currently use, pdoc3.
Determine how to mark things as deprecated (documentation only, or possibly using decorators somehow)
It should both be documented and raise a DeprecationWarning. The documentation will ultimately be our own convention again, it's just another thing to pick and be consistent about.
DeprecationWarnings are done with the standard warnings module . These warnings can be filtered, redirected, etc. by users, so it has all the features you'd want from an SDK like this.
With some care you could maybe write a decorator to handle both these things. The main thing is to make sure that all this stuff tells people what they should use instead.
Determine how to hide private variables/functions/classes from documentation (or possibly not export them at all, but need to be careful about backwards compatibility)
This isn't doable as such. The best you can do is follow the convention of naming these things with a leading underscore, and then reinforce in the documentation you mean it.
pdoc3 will let you configure it to hide documentation for some of these things, but that's specific to pdoc3, other tools like pydoc won't respect it.
Updated by 
Updated by 
Updated by 
