docs2md

自动解析 python 文档字符串并将它们转换为 markdown！

安装

pip install你可以走了！

https://pypi.org/project/docs2md/

指示

只需从命令行运行docs2md.py即可与 ol' main 函数进行交互。

注意：程序使用 f-strings，因此3.6需要 python 或更高版本。

假设您将有一个像这样的文件夹结构：

.
├── foo.py
├── blahbla
│   ├── __init__.py
│   └── blahblah.py
├── LICENSE
└── README.md

运行python3 -m docs2md.py .将产生以下结果：

.
├── docs
│   ├── foo.md
│   └── blahbla
│       ├── __init__.md
│       └── blahblah.md
├── foo.py
├── blahbla
│   ├── __init__.py
│   └── blahblah.py
├── LICENSE
└── README.md

命令行参数如下：

positional arguments:
  f                     File or directory to parse!

optional arguments:
  -h, --help            show this help message and exit
  -d [DOCS_DIR], --docs-dir [DOCS_DIR]
                        Documentation directory in which your .md files will
                        be saved. Defaults to [cwd]/docs
  -p, --just-print      Prints the results instead of creating a whole file!
  -s [SAVE_IMPORT], --save-import [SAVE_IMPORT]
                        Whether you'll want to save the imports to another
                        file. Simply place the path of the txt file you'll
                        want to save your imports to
  --test                Runs doctest!

无论如何，这是如何工作的？

如果输入是一个目录，doc2md.py将 glob 查找 python 文件的所有文件，然后查找 docstrings。

注意：该程序还将包括__init__主文件和主文件，因为这些文件可能包括关键声明。

该yield_docstrings函数将使用 python 的抽象语法树模块来查找以下节点附近的文档字符串：

• 函数定义：

def foo()...

• 异步函数定义：

def async foo()...

• 类定义：

class foo:...

• 模块：

"""docstrings at the start of a file"""

并根据它们自动生成一个简单的降价。随意阅读这个 repo 的 docs 文件夹，它是使用这个工具自然创建的。

该程序还将寻找以下节点：

• 进口于
• 进口

并提到一个python文件从这个或那个模块导入的事实。

（这对于跟踪依赖关系很有用，您可以使用 -s 标志单独保存它们）

截至撰写本文时，该程序尚未包含全局变量或数据。尽管我倾向于将它们包含在未来的更新中。