Contents

• Welcome to docfly Documentation
  • Install
  • Table of Content
• About the Author
  • API Document

---

Welcome to docfly Documentation

docfly is a utility tools to minimize your work using sphinx-doc

Feature:

• Automatic API Reference Doc Generation.
• Easy Table of Content directive Generation (.. toctree::).

Install

docfly is released on PyPI, so all you need is:

$ pip install docfly

To upgrade to latest version:

$ pip install --upgrade docfly

Table of Content

docfly使用说明

docfly 是一个帮助你更容易地使用 sphinx-doc 来构建你的文档网站的工具. 目前有两大杀手级功能:

• 自动生成 API 文档.
• 自动生成 目录.

自动生成 API 文档

如果你在为你的Python代码写文档, Sphinx有一个杀手级的功能: 自动从源代码中摘取docstring, 生成API文档. 然后你就可以使用在你的文档中使用 :ref:`modindex` 引用之. 但是, 你需要手动编写大量代码, 告诉Sphinx哪些模块你想要自动为它生成文档. 具体做法请参考 这篇说明. 也就是说, 你还是需要手动为你的每一个 .py 文件创建 .rst 文件, 然后手动告诉 sphinx 哪些模块和函数需要自动文档.

docfly 的 杀手级功能 是, 只要你指定包的名称, 就能自动分析你的源代码, 然后自动为每一个 .py 文件, 每一个类, 每一个函数, 生成 :ref:`modindex` 所需的一切文件. 并且在你的源代码结构发生变化之后, 自动更新. 下面我们就以 docfly 项目本身为例进行说明。你可以在 这里 找到本文档中的示例代码.

使用的方法很简单, 在你的 conf.py 文件中添加如下代码:

import docfly

#--- Api Reference Doc ---
package_name = docfly.__name__

docfly.ApiReferenceDoc(
    conf_file=__file__, # 指定 conf.py 文件路径
    package_name=package_name, # 指定你要为其自动生成文档的包的名称
    ignored_package=[ # 指定你不想为哪些子模块和子包生成文档
        "%s.pkg" % package_name,
    ]
).fly()

简单来说上面这段代码做了三件事:

1. 告诉 docfly conf.py 文件在哪. 我们好在该目录下创建 .rst 文件.
2. 告诉 docfly 我们要为哪个包生成自动 API 文档.
3. 告诉 docfly 我们要排除掉哪些模块.

自动生成 目录

写一个文档网站就像写一本书. 分Chapter, Section, … 一级一级的往下延伸。而我们希望能自动地从上往下, 为每一章生成它下面每一节的链接, 同理一级一级的传递下去.

根据 sphinx-doc 的 官方文档, 你需要在你要生成目录的地方, 放置如下 Directive:

.. toctree::
    :maxdepth: 1

    Title of your sub document <path-to-the-rst-file>
    ...

也就是说, 你仍然要手动的指定你要在目录中包括哪些子文档. 当你创建了新的 .rst 文件时, 你需要手动将其添加到 Directive 中去.

而 docfly 的另一个重要功能就是: 只要你按照 Sphinx文档项目规范, 那么仅仅使用 .. autotoctree:: 标记, 就能自动发现当前目录下的子目录中的 index.rst 文档, 并在该处生成 .. toctree:: 的索引.

你需要在 conf.py 中添加如下内容:

extensions = [
    ...
    'docfly.directives',
    ...
]

Sanhe’s Sphinx文档项目规范

每一个大型项目, 或是某一类的项目通常都有自己的项目规范. 这些规范都是从大量的实际项目经验中总结而来. 遵循一定的规范可以让你的代码更易读; 而前人的经验往往能帮助你避免很多你所没考虑到的问题.

命名空间

1. 文件名中不要出现空格.
2. 使用 - 连接所有的单词, 而不是 _, 这是因为 - 在Url中是合法字符, 而 _ 不是.
3. 标题避免使用形如 ThisDocument 这样的多个单词不分隔, 因为这样命名可读性较差. 推荐使用而用首字母大写的方式..
4. 尽量使用全英文数字, 不要使用非英语字符, 但如果你必须要这么做, 也并没有问题.

页面

每一个 .rst 文件在文档网站中代表的是一个页面. 笔者推荐, 为你的每一个页面的文档文件, 创建一个 独立的目录. 其中包含 index.rst. 假设你本来想创建一个文件叫 learn-sphinx-doc.rst, 你应该这样做:

source
|--- learn-sphinx-doc # this is a directory
    |--- index.rst
|--- index.rst # root

而不是:

source
|--- learn-sphinx-doc.rst
|--- index.rst # root

这是因为, 你的文件中很可能包含有多个图片, 而你需要在你的文件中引用它们. 为每一个页面创建一个文件夹能够让你每个文件所引用的图片与其他文件的图片分开, 不至于混淆.

图片

如果你使用 页面 一节中的规范, 那么每一个 .rst 文件中所要引用的图片就应该跟 index.rst 保持在同一个目录下. 如果你没有使用前面所说的规范, 那么建议你创建一个和你的 document-title.rst 文件同名的文件夹, 并加上 images 前缀, 例如 images-document-title, 然后将图片放在这一目录内. 这样可以区分开每个文件所使用的图片.

About the Author

(\ (\
( -.-)o    I am a lovely Rabbit!
o_(")(")

Sanhe Hu is a very active Python Developer Since 2010. Research area includes Machine Learning, Big Data Infrastructure, Business Intelligent, AWS, Distributive System. Love photography, outdoor, arts, game, and also the best Python.

• My Github: https://github.com/MacHu-GWU
• My HomePage: http://www.sanhehu.org/

API Document

• by Name
• by Structure