跳转到主要内容

自动生成文档页面

项目描述

Documentation Status PyPI Build Status GitHub

这是一个Python包,用于使用Sphinx自动构建文档页面以记录给定的Python包。 gendocs 允许用户将所有文档直接保留在他们的包中,因为页面直接从代码中的docstrings生成!

连接

想看示例?查看以下使用 gendocs 的项目之一

  • PVGeo:一个用于在VTK和ParaView中可视化地球物理数据的Python包

  • ESPA Tools:一个用于简单加载Landsat图像为NumPy数组的Python包

开始使用

从PyPI安装 gendocs

$ pip install gendocs

Cookiecutter

想轻松创建一个会构建自己的文档的新项目?尝试 gendocs Cookiecutter,它将提示您输入新项目的详细信息,并为您的自动文档化Python包创建所有必要的文件结构。

要创建新项目,请确保您已在虚拟环境中安装了 Cookiecutter

$ pip install cookiecutter

现在您可以使用 我们的Cookiecutter模板 创建新项目,并通过执行以下命令并按照提示操作来准备使用 gendocs

$ cookiecutter https://github.com/banesullivan/cookiecutter-gendocs.git

这样就完成了!现在您有一个准备好的Python项目,可以自动生成文档和部署。

用法

已经有一个需要自动文档的Python包?请按照以下步骤操作。

本生成器是为 Sphinx (RST) 文档构建的。为了记录您的包,请设置 Sphinx 和一个 conf.py 文件,然后在您的 conf.py 文件的顶部附近添加以下内容。

# Import the package to document:
import wonderfulpackage

# Automatically generate documentation pages
from gendocs import Generator
Generator().DocumentPackages(wonderfulpackage)

这样就完成了!上面的代码块是您记录包(们)所需的所有操作。现在您可以构建 Sphinx 文档,所有文档页面都将自动生成。

告知他人

如果您的项目自动生成文档,请在项目中添加一个徽章,以告知他人!我们希望这些徽章能够激发好奇心、参与度以及社区对 gendocs 包的贡献。

Markdown

[![Documentation Built by gendocs](https://img.shields.io/badge/docs%20by-gendocs-blue.svg)](https://gendocs.readthedocs.io/en/latest/)

RST / Sphinx

.. image:: https://img.shields.io/badge/docs%20by-gendocs-blue.svg
   :target: https://gendocs.readthedocs.io/en/latest/
   :alt: Documentation Built by gendocs

贡献

请访问 GitHub 上的 gendocs 以贡献并使自动文档变得更加完善!

由以下机构支持

AWS AWS 云计算和安全赞助商 Datadog Datadog 监控 Fastly Fastly CDN Google Google 下载分析 Microsoft Microsoft PSF 赞助商 Pingdom Pingdom 监控 Sentry Sentry 错误记录 StatusPage StatusPage 状态页面