pyMkDocs 实用程序

什么是 pyMkDocs？

pyMkDocs 是一个为 Python 项目生成文档的工具。它扩展了MkDocs的功能。它本身是用Python编写的。

为什么创建这个项目？

MkDocs是使用 Markdown 生成网站的绝佳工具。然而，到目前为止，还没有从 Python 源代码自动生成MkDocs 项目的工具。

比较 Python 文档生成器的典型起点是标准库的pydoc模块。虽然该工具易于使用，但并不灵活，最终结果仍有待改进。相比之下，许多人会认为自动生成 Python 文档的“黄金标准”是Sphinx。但是该工具很复杂，并且使用 reStructuredText。太糟糕了 reStructuredText糟透了， Markdown 摇滚！

由于记录代码所涉及的实际工作最终将围绕以一种或另一种方式编写Doc Strings为中心，因此能够通过 Markdown 在该上下文中表达自己将使您在很长一段时间内都很开心！

我该如何安装它？

pip install pymkdocs

使它起作用的食谱：

• 原料：

  • 1 个包含 Python 源文件的example文件夹（例如这个 repo 中的文件夹） 或1 个新的pip install
  • （可选）源中包含的自定义文档字符串和/或“魔术注释”（见下文）

• 简单的步骤：

  • 安装 pyMkDocs。
  • 打开终端并切换到项目目录。例子：cd pymkdocs
  • 运行 pyMkDocs。例子：pymkdocs example/src example -r -c -s

命令行帮助：

| pyMkDocs |
This utility generates MkDocs websites from Python source code.
Help:  pymkdocs -h/--help
Usage: pymkdocs source destination [-m/-r] [-c] [-s]
-m: magic mode (default) / -r: raw mode
-c: include source code
-s: serve test site

这是如何运作的？

pyMkDocs 分析您的 Python 源代码并从中生成降价文件。然后它使用 MkDocs 从 markdown 生成基于 html 的文档！此过程创建：

• 一个“mkdocs.yml”文件，它是MkDocs的配置文件
• 一个“文档”文件夹，包含降价
• 一个“站点”文件夹，这是最终生成的网站

原始模式

学习使用 pyMkDocs 的最简单方法可能是首先运行“原始模式”中提供的示例。通过-r命令行上的开关来启用此选项。使用此方法生成文档，递归扫描指定源路径的整个目录树，并对代码的所有元素进行索引。生成的文件具有 Python 包/模块与子目录/文档（即站点页面）的直接一对一对齐。

这是以文字方式索引在该 Python 代码库中找到的确切源的最直接样式。

魔法模式

既然您已经看到使用“原始模式”是多么容易，那么让我们深入了解“魔术模式”吧！

“魔术模式”用于以更加动态、可定制的方式生成文档站点。此模式与“原始模式”之间的主要区别在于，对象被索引的方法是“通过导入”而不是“文件路径”。此模式还提供了在显着程度上定义生成的内容结构的方法。

在此模式下找到对象的方式与通过 Python 运行时上下文中的导入自然解析包内容的方式一致。明确包含在给定 Python 包的模块中的源元素__init__将由文档生成器的解析器/检查器索引。

为“源”参数传递的命令行参数可能只是导入的名称。使用此模式时，该参数不必是其目录的路径。因此，在“pip 安装”任何库（包括来自远程或本地源）之后，您可以通过 import namepyMkDocs 对其运行来跟进它！

作为奖励，当使用此模式时，如果将“魔术注释”（使用为此特定工具定义的语法）放置在__init__正在扫描的此类模块中，则将被处理。这用于指示降价文件/站点页面将如何命名和排序，以及生成的内容。

让我们看一个示例“magic init”文件......

示例/src/ init .py：

"""
This library is very impressive... :)
"""
# docs > Introduction.md
# docs : __doc__ 

#------------------------------------------------------------------------------
# docs > Mini.md
""" docs : prose
Here is some preamble text for the page...  
"""
from .functions import mini, MIN_SIZE
""" docs : prose
Closing comments on these functions...  
"""

#------------------------------------------------------------------------------
# docs > Shark.md
""" docs : prose
This page is devoted to the **Shark**.  
"""
from .class_and_function import Shark, maxi

#------------------------------------------------------------------------------
# docs > null
from os import abc 

#------------------------------------------------------------------------------
# docs > Config Parser.md
""" docs : virtual
from configparser import ConfigParser
""" 

当客户端执行时（假设可以找到包），这个__init__文件自然地控制了通过 Python 导入系统可以访问的内容。import src此文件中定义的项目由 Python 解释器导入。当被此工具扫描时，它们也会自动记录，同时处理解释器忽略的“魔术注释”。

__init__您的模块中可能包含以下魔术注释命令。

开始写作：# docs > [Page Name].md

以此开头的注释行，表示要写入给定降价文件的起点。该文件/页面将由该docs >前缀后面的内容命名。请注意，索引并包含在结果文件中的源内容可能来自您系统上的任何可导入模块/包 - 而不仅仅是您的源！

散文：

""" docs : prose
This markdown appears where ever you want in the current document.
"""

按照这种注释模式，将此降价“写入”到当前文档。

包文档字符串：# docs : __doc__

将包文档字符串注入当前文档。

丢弃：# docs > null

丢弃后面任何源代码的文档。

虚拟代码：

""" docs > virtual
is_virtual_code_cool = True
"""

遵循这种注释模式，该工具执行的解析/对象检查将就像虚拟代码实际存在一样，但不必真正包含在您的项目中。这提供了一种以完全开放的方式创建文档的方法，该方式不与任何文字源紧密绑定。

最小的项目布局

• 在 pyMkDocs 之前：

 src/
     ...         # Other python files or folders

• 在 pyMkDocs 之后：

 mkdocs.yml      # The configuration file.

 src/
     ...         # Other python files or folders

 docs/
     index.md    # The documentation homepage.
     ...         # Other markdown pages, images and other files.

 site/           # The static site ready to be hosted
     index.html
     ...

自定义内容

pyMkDocs 不仅限于从头开始生成站点。相反，它可以与您的自定义内容动态集成。一旦您知道如何操作，添加您自己的页面、添加更多 MkDocs扩展、添加插件、修改站点主题等等就很容易 了！

更新模式

启动pyMkDocs 项目的最简单方法是首先允许该工具为您创建一个基本站点。之后，您可以编辑mkdocs.yml生成的文件。当该工具随后再次运行时，它将检测该先前配置的存在，然后以“更新模式”运行。

mkdocs.yml在“更新模式”中， pyMkDocs 将修改的唯一部分是在“参考”部分中找到的部分。在 MkDocs 重新生成站点时，您自定义的任何其他内容都将得到完全保留和尊重。

要了解有关如何修改mkdocs.yml文件的更多信息，请参阅 MkDocs 配置指南。

混合模式

还提供了另一种“混合模式”。这是从头开始或作为纯粹的“更新”操作之间的中间地带。

要使用此方法：

• 删除现有mkdocs.yml文件（如果适用）
• 创建一个docs文件夹（如果不存在）
• 将自己的Markdown 文件添加到docs文件夹中
• 运行 pyMkDocs！

这样做的结果将类似于创建一个全新的站点，接受您预先存在的 Markdown 文件将用于生成站点页面，它们将自动添加到您的目录的顶层！

主页

当访问者首次浏览该站点时，将显示其“主页”页面。此页面是从名为index.md（命名为默认网站页面：）的 Markdown 文件创建的index.html。

如果您的文件夹中不存在此文件docs，pyMkDocs 将为您生成一个简单的占位符。要修改此页面的内容，只需编辑或替换index.md源即可。

属性文档字符串

Python 文档字符串的正式标准在 PEP-257中定义。它们不包括“属性文档字符串”。因此，没有官方方法来记录如何使用类和模块属性。造成这种情况的主要原因是无法就开发人员在实践中采用这种标准的最简洁方式达成共识。遵循如何使用模块、类和函数完成此操作的规则（在对象签名后添加三重双注释）对某些人来说似乎有些过分或令人困惑。此外，人们相信属性应该是“自我记录的”，只需为它们使用好名字。

也就是说，有人建议非官方文档生成器（例如这个）可能仍希望遵守被拒绝的 PEP-224或 PEP-258中提出的 关于属性的标准。因此，pyMkDocs 在生成文档时会识别这些约定并处理此类注释。

推荐的函数文档字符串

代码：

def fun(arg1: int, arg2: str = 'Hello World!'):
    """Description of your function

    **Parameters**

    > **arg1:** `int` -- Description of argument `arg1`.

    > **arg2:** `str` -- Description of argument `arg2`.

    **Returns**

    > `str` -- Description of returned object.
    """
    return arg2 + str(arg1)

截屏：

想要更多？

查看示例源。在那里，您会发现大量精美的元素，您现在可以立即将其添加到您的文档中，利用许多 MkDocs扩展的强大功能！

怎么办？

一旦您为静态网站生成了源以显示您的惊人文档，您如何将其提供给您的用户/目标受众？

当然，您可以通过多种方式设置网站托管（这些都远远超出了本文档的范围！）。完成后，您可以简单地将文件上传到那里。也就是说，对于这个特定目的，一个非常显着的选择是使用 GitHub Pages ，它是免费、快速和简单的。

使用 GitHub Pages，您可以创建一个专用于该站点的新GitHub 存储库，或者您可以将GitHub Pages 站点添加到现有存储库（例如您的项目源）。可以说，如果您正在记录的代码已经在 GitHub 上，或者您打算将其发布到那里，则后者更有意义。有关这方面的更多信息，请参阅：创建 GitHub 页面站点

请注意，GitHub Pages 允许您从存储库的根目录或名为docs. 无法自行定义此路径，也无法使用名为site.

虽然 GitHub Pages 支持基于 Markdown 的站点，因此可以使用 docs包含此类内容的目录，然后它将通过与您已经使用 MkDocs 生成的内容不同的机制将其转换为 html。如果您想将 GitHub Pages 站点添加到现有存储库，那么您是否希望它在root上是值得怀疑的，因此为了在本地发布您的站点，您需要放置通常是“站点”的内容目录中的内容docs 。幸运的是，这很容易解决！只需重命名您的文件夹并将以下行添加到您的mkdocs.yalm文件中：

docs_dir: docs_src
site_dir: docs

然后 pyMkDocs 将自动生成 Markdown 到一个docs_src文件夹中，MkDocs 将在docs. 问题解决了。