Sage手册

Sage的手册是用 ReST (structuredText),并使用软件生成 Sphinx

名字

文件夹

Tutorial

SAGE_ROOT/src/doc/en/tutorial

Developer's guide

SAGE_ROOT/src/doc/en/developer

Constructions

SAGE_ROOT/src/doc/en/constructions

Installation guide

SAGE_ROOT/src/doc/en/installation

Reference manual

SAGE_ROOT/src/doc/en/reference (大部分是源代码生成的)

  • 此外,更多专门的手册可以在下面找到 SAGE_ROOT/src/doc/en .

  • 一些文件 翻译 翻译成其他语言。为了访问它们,将en/改为fr/、es/、de/。。。看到了吗 文件名称 .

编辑文档

是否要将Sage工作表转换为文档? Click here

在Sage教程中修改了一些文件之后 (SAGE_ROOT/src/doc/en/tutorial/ ),您将希望可视化结果。为了建立一个 html 文件类型:

sage --docbuild tutorial html

你现在可以打开了 SAGE_ROOT/local/share/doc/sage/html/en/tutorial/index.html 在您的网络浏览器中。

  • 你想吗 添加新文件 到文件里去了? Click here .

  • 有关 --docbuild 命令,请参阅 编写手册 .

运行doctests: 所有文件必须通过测试。修改文档后(例如。 tutorial ),可以使用以下命令运行测试(请参见 运行自动文档测试 ):

sage -tp SAGE_ROOT/src/doc/en/tutorial/

参考手册: 由于本手册主要是从Sage的源代码生成的,因此您需要构建Sage,以便查看您对某些函数文档所做的更改。类型:

sage -b && sage --docbuild reference html

添加新文件

如果您在Sage中添加了一个新文件(例如。 sage/matroids/my_algorithm.py )如果你想让它的内容出现在参考手册中,你必须把它的名字添加到文件中 SAGE_ROOT/src/doc/en/reference/matroids/index.rst . 把“拟阵”换成适合你情况的东西。

The combinat/ folder: 如果新文件属于combinat/的子目录,则过程不同:

  • 将文件添加到存储在 __init__.py 文件位于包含文件的目录中。

  • 将文件添加到中包含的索引 SAGE_ROOT/src/doc/en/reference/combinat/module_list.rst .

编写手册

(是否要编辑文档? Click here

所有的Sage手册都是使用 sage --docbuild 脚本。的内容 sage --docbuild 脚本在中定义 SAGE_ROOT/src/sage_setup/docbuild/__init__.py . 它是一个薄薄的包装 sphinx-build 完成所有实际工作的脚本。它被设计为替换由 sphinx-quickstart 脚本。命令的一般形式是:

sage --docbuild <document-name> <format>

例如::

sage --docbuild reference html

Two help commands which give plenty of documentation for the sage --docbuild script:

sage --docbuild -h # short help message
sage --docbuild -H # a more comprehensive one

输出格式: Sphinx支持的所有输出格式(例如pdf)都可以在Sage中使用。看到了吗 http://sphinx.pocoo.org/builders.html .

断开的链接: 为了在报告文档包含的断开链接的同时生成文档,请使用 --warn-links 旗子。请注意,Sphinx不会重新生成尚未更新的文档,因此不会报告其断开的链接:

sage --docbuild --warn-links reference html

文件名称

这个 <document-name> 具有以下形式:

lang/name

在哪里? lang 是两个字母的语言代码,并且 name 是文档的描述性名称。如果未指定语言,则默认为英语 (en ). 以下两个命令执行完全相同的操作:

sage --docbuild tutorial html
sage --docbuild en/tutorial html

要指定教程的法语版本,只需运行:

sage --docbuild fr/tutorial html

语法突出显示Cython代码

如果你想写 Cython 代码在ReST文件中,在代码块之前 .. CODE-BLOCK:: cython 而不是平常 :: . 在整个文件中启用语法高亮显示 .. HIGHLIGHT:: cython .例子:

cdef extern from "descrobject.h":
    ctypedef struct PyMethodDef:
        void *ml_meth
    ctypedef struct PyMethodDescrObject:
        PyMethodDef *d_method
    void* PyCFunction_GET_FUNCTION(object)
    bint PyCFunction_Check(object)