markdocs 0.0.0

Python文档

我喜欢使用Markdown在Rustlang中编写功能文档，所以我将进行实验以在Python中实现相同的功能。看看rustdoc和这里一个示例，这是一个使用Markdown注释生成的Rust crate的文档网站。

信息是通过使用python -m tokenize file.py https://docs.pythonlang.cn/3.5/library/tokenize.html#examples

Markdown

如何工作

注意：这只是一个初步的想法，尚未实现！如果喜欢，请评论。

Markdocs从所有.py文件中提取文档，并输出到一个有组织的文档html网站，可以使用mkdocs.org来暴露和部署。

markdocs /path/to/project

如果您不想生成完整的文档，您可以轻松地为您的仓库生成一个README文件。

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

使用上述方法，将生成一个包含仅过滤文件和对象文档的README.md，但您也可以为整个项目生成单个README。

该文件夹中的所有.py文件都将被解析以查找文档块，这些块是以!开始的Python多行注释。

注意：如果您不喜欢将代码和文档混合，可以使用 mymodule.md 来记录 mymodule.py，且.md 文件应位于同一文件夹或项目的 mdocs 文件夹中。您也可以像 mymodule.myclass.mymethod.md 这样编写单独的对象文件，它只会链接到 MyClass 的 mymethod。

"""!
# 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 https://mkdocs.pythonlang.cn/
- 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(..):
            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