UNDER DEVELOPMENT HERE: https://github.com/rochacbruno/markdocs
I still think that the problem of lack of good documentation in the Python ecosystem is also related to .rst format and the use of complicated tools like Sphinx.
I'm enjoying writing functional documentation using Markdown in Rustlang, so I'll do experiments to have the same functionality in Python. Take a look at rustdoc and here an example of documentation site generated for a Rust crate using markdown comments.
Information is extracted using python -m tokenize file.py https://docs.python.org/3.5/library/tokenize.html#examples
NOTE: this is just an early stage idea, not implemented yet! if you like please comment.
The Markdocs extracts documentation from all .py files and outputs in a well organized documentation html site which can use the mkdocs.org to expose and deploy.
markdocs /path/to/projectIf you dont want to generate full documentation you can easily generate a readme file for your repo
markdocs /path/project --readme README.md -k 'filter-oly-some-files-and-objects'With the above a README.md is generated including only the filtered files and objects documentation, but you can also generate a single README for your whole project.
All .py files on that folder will be parsed for documentation blocks which are Python multiline comments starting in ! example:
NOTE: if you don't like mixing code and documentation, you can use a
mymodule.mdto documentmymodule.pyand the.mdshould be located in the same folder or inmdocsfolder of the project. You can also write separated object files like inmymodule.myclass.mymethod.mdwhich will be linked only to themymethodofMyClass.
"""!
# this is a documentation written in markdown
As it has only one `!` at the top, it is considered the module documentation
I can include module documentation along the file and will be merged in to the top level documentation
"""
from foo import bar
"""!!
# This is an object documentation, can be used for any object but most for functions and classes
It is defined before the object and not on the `__doc__` docstring, as markdocs does not conflicts with it.
## What are the advantages
- Markdown is easy to learn
- More people will contribute to documentation because they already know the format
- With simple commands like `markdocs /path --readme README.md` the readme for your repo is generated from markdocs
- Markdocs will generate the output for http://www.mkdocs.org/
- You can write bare `.md` files in a `mdocs` folder and they will be added to you documentation as well
[[params
# X is the single param of this function
x: int | default 0
# The return is a string with the x interpolated.
]] result: str
"""
def a_function(x=0):
"""This regular docstring does not conflicts with the above markdoc"""
return f'Hello {x}'
"""!!
# This is a class documentation
We can also define runnable and highlighted blocks of code.
```run
obj = MyClass()
```
"""
class MyClass:
"""the class docstring is not affected"""
attr = 'foo'
"""!!!
# this is a method documentation
[[params
x: str
]]
"""
def method(self, x):
"""This is the regular docstring for method"""
a = x
"""!!!!
## Here we increase the nesting level
Markdown is amazing!
"""
def inner_function(..):
passAs you can see the !! can be also used, in fact you can use as many !!!!! you want to define nesting.
Parser options are:
Website output formats
- mkdocs.org
- https://github.com/rocadocs/rocadocs
https://github.com/jeanralphaviles/comment_parser
http://commonmark.org/help/