Documentation Documentation AKA Meta-Documentation

How to build documentation

让我们说你正在写文档,并且想在你推送之前看到sphinx输出。文档将在html目录中生成。

cd Theano/
python ./doc/scripts/docgen.py

如果你不想生成pdf,请执行以下操作:

cd Theano/
python ./doc/scripts/docgen.py --nopdf

更多细节:

$ python doc/scripts/docgen.py --help
Usage: doc/scripts/docgen.py [OPTIONS]
  -o <dir>: output the html files in the specified dir
  --rst: only compile the doc (requires sphinx)
  --nopdf: do not produce a PDF file from the doc, only HTML
  --help: this help

Use ReST for documentation

  • ReST是标准化的。trac wiki-markup不是。这意味着ReST可以在代码,其他文档和TRAC之间进行剪切和粘贴。这是一个巨大的胜利!
  • ReST是可扩展的:例如,我们可以编写自己的角色和指令来自动链接到WIKI。
  • ReST有图和表指令,可以转换(使用标准工具)到乳胶文档。
  • 没有文本文档对数学渲染有很好的支持,但是ReST最接近:它有三个渲染器特定的解决方案(render latex,使用latex为html构建图像,使用itex2mml生成MathML)

How to add TODO comments in Sphinx documentation

要在Sphinx文档中包含TODO注释,请使用缩进块,如下所示:

.. TODO: This is a comment.
.. You have to put .. at the beginning of every line :(
.. These lines should all be indented.

它不会出现在生成的输出中。

How documentation is built on deeplearning.net

承载theano文档的服务器大约每2小时运行一次cron作业,它会获取一个新的Theano安装(克隆,而不仅仅是pull)并执行docgen.py脚本。然后使用新生成的文档覆盖以前的文档。

注意,服务器将绝对使用不同版本的sphinx比你的,所以格式化可能会稍微偏离,甚至是错误的。如果你得到不正常的结果和/或文档的自动构建似乎中断,请联系theano-dev @。

在将来,我们可能会回到自动刷新系统(尽管这可能会增加服务器的负载相当大)。

pylint

pylint输出不再自动生成。

Pylint文档是使用pylintrc文件生成的:Theano/doc/pylintrc

The nightly build/tests process

我们使用Jenkins软件来运行Theano,libgpuarray和Deep Learning Tutorial的每日buildbots。Jenkins下载/更新repos,然后运行它们的测试脚本。这些脚本在各种条件下测试项目。Jenkins还在32位Python 2.7和Python 3.4中为Theano运行了一些测试。

输出将自动通过电子邮件发送到theano-buildbot邮件列表。jenkins日志和测试报告在线发布:

TO WRITE

此处还有其他文件,例如:

  • 我们还想要好的文档的例子,向人们展示如何编写ReST。