Sage手册¶
Sage的手册是用 ReST (structuredText),并使用软件生成 Sphinx :
名字 |
文件夹 |
---|---|
|
|
|
|
|
|
|
|
|
此外,更多专门的手册可以在下面找到
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
超链接¶
文档可以包含指向模块、类或方法的链接,例如:
:mod:`link to a module <sage.module_name>`
:mod:`sage.module_name` (here the link's text is the module's name)
对于指向类、方法或函数的链接,请替换 :模式: 通过 :等级: , :方法: 或 功能: 分别。看到了吗 Sphinx' documentation .
短链接: 链接 :func:`~sage.mod1.mod2.mod3.func1
相当于 `func1 <sage.mod1.mod2.mod3.func1>`()
`:函数的名称将用作链接名称,而不是其完整路径。
本地名称: 同一个类的方法之间的链接不需要是绝对的。如果你在记录 method_one
,你可以写 :meth:`method_two
'.
全局命名空间: 如果一个物体(例如。 integral
)是由Sage自动导入的,您可以链接到它,而无需指定其完整路径:
:func:`A link toward the integral function <integral>`
Sage-specific roles: Sage定义了几个具体的 角色 :
Trac服务器 |
|
|
维基百科 |
|
|
阿尔十四 |
|
|
整数序列在线百科全书 |
|
|
数字目标标识符 |
|
|
MathSciNet |
|
http链接: 在文档中复制/粘贴http链接。如果需要特定的链接名称,请使用 `link name <http://www.example.com>`_
断开的链接: 斯芬克斯可以报告断开的链接。看到了吗 编写手册 .
添加新文件¶
如果您在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)