《Sage手册》

Sage的手册是用 ReST )，并使用软件生成 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 。

  • 一些文件已经被 translated 翻译成其他语言。要访问它们，请更改 en/ vt.进入，进入 fr/ ， es/ ， de/ ..。看见 文档名称 。

编辑文档

在修改Sage教程中的一些文件后 (SAGE_ROOT/src/doc/en/tutorial/ )，您将希望可视化结果。为了建立一个 html 本文档的版本，请键入：：

sage --docbuild tutorial html

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

  • 你想不想 add a new file 到文件里吗？ Click here 。

  • 要了解更多有关 --docbuild 命令，请参见 构建手册 。

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

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

Reference manual: 由于本手册主要是从Sage的源代码生成的，因此您需要构建Sage才能看到您对某些函数的文档所做的更改。类型：：

sage -b && sage --docbuild reference html

添加新文件

如果您向Sage添加了一个新文件(例如 sage/matroids/my_algorithm.py )，并且希望其内容出现在参考手册中，则必须将其名称添加到文件中 SAGE_ROOT/src/doc/en/reference/matroids/index.rst 。用任何符合你的情况的词来代替‘matroid’。

The combinat/ folder: 如果您的新文件属于Composat/的子目录，则该过程不同：

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

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

使参考手册的某些部分以可选功能为条件

对于每个可动态检测的功能，例如 graphviz 或 sage.symbolic (见 sage.features )，Sage定义了一个可与 Sphinx directive ".. ONLY::" 。因为Sphinx标签必须使用Python标识符语法，所以Sage使用以下格式 feature_ ，后跟用下划线替换圆点的功能名称。因此，根据前面示例的功能设置条件如下所示：

.. ONLY:: feature_graphviz

以及：

.. ONLY:: feature_sage_symbolic

构建手册

(Do you want to edit the documentation? Click here )

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

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

例如：：

sage --docbuild reference html

二 help 命令，这些命令为 sage --docbuild 脚本：：

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

Output formats: Sage中可以使用Sphinx支持的所有输出格式(例如pdf)。看见 http://www.sphinx-doc.org/builders.html 。

Broken links: 为了在报告文档中包含的断开链接的同时生成文档，请使用 --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)