4. Use sphinx-apidoc

Context and Problem Statement

We would like to automatically generate api docs using the doc strings of our methods. What tool should we use to generate those?

Decision Drivers

• Ease of use, the more automatic the tool is the better

• Well supported, we don’t want the tool we use to suddenly go away

• Supports type annotations, we would like to minimize the duplication of type information if at all possible

Considered Options

• sphinx-apidoc

• sphinx autoapi

Decision Outcome

“sphinx-apidoc”, because it is distributed with sphinx and supports type annotations.

Pros and Cons of the Options

sphinx-apidoc

• Good, because it is distributed with sphinx

• Good, because it supports type annotations

• Bad, because it requires running a separate tool to generate the api docs

• Bad, because migration will take work

sphinx autoapi

• Good, because we are already using it

• Bad, because we now rely on a third party

• Bad, because its type annotation support is “experimental” and may be removed