Package: markdocs
Extract markdown from Python source file comments and outputs structured
documentation & README file.Python documentationI’m enjoying writing functional documentation usingMarkdowninRustlang, so I’ll do experiments to have the same functionality in
Python. Take a look atrustdocandhere an exampleof documentation site generated for a Rust crate usingmarkdown
comments.Information is extracted usingpython-mtokenize file.pyhttps://docs.python.org/3.5/library/tokenize.html#examplesMarkdownHow it worksNOTE: this is just an early stage idea, not implemented yet! if you
like please comment.TheMarkdocsextracts documentation from all.pyfiles and outputs
in a well organized documentationhtmlsite 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 repomarkdocs/path/project--readmeREADME.md-k'filter-oly-some-files-and-objects'With the above aREADME.mdis generated including only the filtered
files and objects documentation, but you can also generate a single
README for your whole project.All.pyfiles 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 amymodule.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
"""fromfooimportbar"""!!
# 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
"""defa_function(x=0):"""This regular docstring does not conflicts with the above markdoc"""returnf'Hello{x}'"""!!
# This is a class documentation
We can also define runnable and highlighted blocks of code.
```run
obj = MyClass()
```
"""classMyClass:"""the class docstring is not affected"""attr='foo'"""!!!
    # this is a method documentation
    [[params
       x: str
    ]]
    """defmethod(self,x):"""This is the regular docstring for method"""a=x"""!!!!
        ## Here we increase the nesting level
        Markdown is amazing!
        """definner_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:https://github.com/miyuchina/mistletoe/https://github.com/lepture/mistune#lexersWebsite output formatsmkdocs.orghttps://github.com/rocadocs/rocadocsmore onhttps://gist.github.com/rochacbruno/1689c849f3ef54086772c410d77a82de