Generate API docs from Cython sources

[cztomczak]

• Create apidocs.py tool to generate API docs from sources. It should also call DocToc to generate table of contents. Generated markdown file should contain a comment that it was auto-generated from sources and should not be modified. This tool needs a mechanism to decide for which .pyx files to generate doc - if there is a corresponding .md file for a .pyx file it should do it (cefpython/browser.pyx <=> docs/objects/Browser.md). When there is a new .pyx file that needs a doc just create an appropriate .md file. Such file should contain a html comment <!-- Generated by tools/apidocs.py --> and only files that contain such comment should be overwritten to avoid mistakes.
• Use Sphinx doc conventions for docstring:
  • http://www.sphinx-doc.org/en/stable/domains.html (func params)
  • Kivy seem to use Sphinx, but its parameters formatting is different, investigate why. See vertex_instructions.pyx.
  • On cython-users I've found a discussion about documenting Cython code and plans to create a Cython plugin for Sphinx, so +1 for using Sphinx conventions
• See also PEPs:
  • PEP 216 - Docstring Format
  • PEP 224 - Attribute Docstring
  • PEP 256 - Docstring Processing System Framework
  • PEP 257 - Docstring Conventions
  • PEP 287 - reStructuredText Docstring Format
• Also take a look at this StackOverflow answer that mentions reStructureText and Sphinx as the most popular standards in Python.
• Documenting callbacks (handlers and others) may require more effort. See Issue Expose handlers as classes/interfaces: ClientHandler, DisplayHandler, LifespanHandler, etc. #215 - "Expose handlers as classes/interfaces". When such interfaces are available we can use them to generate docs.
• The translator.py tool (Issue Create translator.py tool to provide full CEF API coverage in an automated way  #214) will generate classes for most of the CEF constants/types. In docs only these will be included, CEF uppercase constants will still be kept for BC, but won't be visibile in official docs.
• In Python and in Cython as well any module or object that has a docstring will have this comment accessible in a __doc__ attribute.

[jegger]

I would really favor such a documentation.
It seems to me that Kivy generates doc pages out of cython code.
Example: source doc
But I'm not sure how they do it - I didn't looked into it...