Markdocs - Python documentation using markdown

documentation, documentation-generator, documentation-tool, markdown, markdown-parser, markdown-parsing, python, python-documentation
pip install markdocs==0.0.0



Extract markdown from Python source file comments and outputs structured documentation & README file.

Python documentation

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


How it works

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 to expose and deploy.

markdocs /path/to/project

If you dont want to generate full documentation you can easily generate a readme file for your repo

markdocs /path/project --readme -k 'filter-oly-some-files-and-objects'

With the above a 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 to document and the .md should be located in the same folder or in mdocs folder of the project. You can also write separated object files like in which will be linked only to the mymethod of MyClass.

    # 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` the readme for your repo is generated from markdocs
    - Markdocs will generate the output for
    - You can write bare `.md` files in a `mdocs` folder and they will be added to you documentation as well
      # 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.
    obj = MyClass()
    class MyClass:
        """the class docstring is not affected"""
        attr = 'foo'
        # this is a method documentation
           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(..):

As 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

more on