Generate API reference pages

[florimondmanca]

Is your feature request related to a problem? Please describe. Pydoc-Markdown has been added to the repo, we can now start writing API reference documentation. Ideally all public classes, functions and constants in Bocadillo should appear in the API reference. This issue is to describe how to write such API reference docs.

Describe the solution you'd like First, install the repo as described in the CONTRIBUTING guide (including the Documentation section). Then, run the docs server (npm start).

For each module inside the bocadillo package, we need to:

• Update the generate section of pydocmd.yml with an entry like:

  # pydocmd.yml
  generate:
  - <module_name.md>:
  - bocadillo.<module_name>+

• Open said module and clean up the docstrings (most of which are written in NumPy style, which is fairly close to Pydoc-Markdown's format) by:

  • Fixing the header of any section by using # Header format (no ---- underline)
  • Replacing lines like parameter : type1[, optional] with parameter (type1):
  • Another catch is to not use colons : in special sections (like Parameters, Returns or Attributes). Colons clash with Pydoc-Markdown's formatting. Try to replace them with something else, like a space or a comma. Caution: Markdown links (http://...) won't work either… you should instead reference links outside of special sections.

To preview the result (and everytime you want to see changes), run $ pydocmd generate in the terminal. Then open the docs site and check that the formatting is fine. You may have to hack a bit to get it right.

Describe alternatives you've considered I could generate the pages myself, but this is also a great opportunity for new contributors to get started and discover the repo. :blush:

Additional context For more details about Pydoc-Markdown and its formatting rules, check out their docs.

[florimondmanca]

Done!