markdocs 0.0.0

python文档

我很喜欢使用Markdown在 rustlang，因此我将在 Python。看一看 rustdoc 和here an example 使用markdown comments为生锈的板条箱生成的文档站点。

使用^{tt1}提取信息$ https://docs.python.org/3.5/library/tokenize.html#examples

Markdown

工作原理

NOTE: this is just an early stage idea, not implemented yet! if you like please comment.

markdocs从所有.py文件和输出中提取文档 在一个组织良好的文档html站点中，可以使用 要公开和部署的mkdocs.org

markdocs /path/to/project

如果不想生成完整的文档，可以轻松生成 回购的自述文件

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

使用上面的aREADME.md生成，只包括筛选的 文件和对象文档，但也可以生成 为你的整个项目准备

该文件夹上的所有.py文件都将被解析为文档块 以下是以!开头的Python多行注释示例：

NOTE: if you don’t like mixing code and documentation, you can use a ^{tt5}$ to document ^{tt6}$ and the ^{tt7}$ should be located in the same folder or in ^{tt8}$ folder of the project. You can also write separated object files like in ^{tt9}$ which will be linked only to the ^{tt10}$ of ^{tt11}$.

"""!
# 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(..):pass

正如您所看到的，还可以使用!!，实际上您可以使用 !!!!!要定义嵌套

解析器选项是：

• https://github.com/miyuchina/mistletoe/
• https://github.com/lepture/mistune#lexers

网站输出格式

• mkdocs.org
• https://github.com/rocadocs/rocadocs

更多关于 https://gist.github.com/rochacbruno/1689c849f3ef54086772c410d77a82de