sphinx 文档_Sphinx轻松漂亮的文档

最新推荐文章于 2024-06-01 10:03:07 发布

cuxiong8996

最新推荐文章于 2024-06-01 10:03:07 发布

阅读量2.2k

点赞数

文章标签： python linux java 大数据 html

原文链接：https://www.ibm.com/developerworks/opensource/library/os-sphinx-documentation/index.html

版权

sphinx 文档

Sphinx是允许开发人员以纯文本格式编写文档的工具，可轻松生成满足各种需求的格式的输出。使用版本控制系统跟踪更改时，这将很有帮助。纯文本文档对于跨不同系统的协作者也很有用。纯文本是当前可用的最可移植的格式之一。

尽管Sphinx是用Python编写的，最初是为Python语言文档创建的，但它不一定以语言为中心，在某些情况下甚至不是特定于程序员的。 Sphinx有许多用途，例如编写整本书！

突出显示

Sphinx默认情况下具有针对Python的代码突出显示功能，但它也允许定义其他编程语言，例如C和Ruby。

将Sphinx视为文档框架：它抽象了繁琐的部分，并提供了自动功能来解决常见问题，例如标题索引和特殊代码突出显示（如果显示代码示例）以及适当的语法突出显示。

要求

使用Linux®或UNIX®终端（也称为控制台或终端仿真器）时，您应该感到自在，因为命令行界面是与Sphinx交互的主要方式。

需要安装Python。它已预先安装，可以在所有主要的Linux发行版和某些基于UNIX的操作系统（如Mac OSX）中使用。 Sphinx应该与Python 2.4、2.5和2.6版本一起使用。为了确保您拥有Python和有效版本，请运行清单1中的命令。

清单1.检查Python版本

$ python --version
Python 2.6.1

句法

Sphinx使用reStructuredText标记语法（带有一些附加功能）来提供文档控制。如果您曾经写过纯文本文件，那么您可能已经相当了解精通Sphinx所需的语法。

标记允许文本的定义和结构以正确输出。在开始之前，请参见清单2以获得标记语法的一个小示例。

清单2. Sphinx标记语法示例

This is a Title
===============
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.

Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length 
of the subtitle itself, just like titles.

Lists can be unnumbered like:

 * Item Foo
 * Item Bar

Or automatically numbered:

 #. Item 1
 #. Item 2

Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo`` 
gives you super user powers!

如您所见，该语法在纯文本中看起来非常可读。当需要创建一个特定格式（如HTML）时，标题看起来像是主要标题，并且字体比字幕要大（应有的字体），并且已对编号的列表进行了正确的编号。您已经拥有了相当强大的功能。添加更多项目或更改编号列表中的顺序不会影响编号，标题可以通过替换使用的下划线来更改重要性。

安装与配置

安装在命令行中进行，非常简单，如清单3所示。

清单3.安装Sphinx

$ easy_install sphinx
Searching for sphinx
Reading http://pypi.python.org/simple/sphinx/
Reading http://sphinx.pocoo.org/
Best match: Sphinx 1.0.5
Downloading http://pypi.python.org/packages/[...]
Processing Sphinx-1.0.5-py2.5.egg
[...]
Finished processing dependencies for sphinx

为了简洁起见，清单3进行了简化，但是它提供了一个示例，说明了安装Sphinx时的期望。

该框架使用目录结构在源（纯文本文件）和内部版本（这是指生成的输出）之间进行分隔。例如，如果Sphinx被指示从文档来源生成PDF，则该文件将被放置在build目录中。可以更改此行为，但是为了保持一致，我们将使用默认格式。

让我们快速启动清单4中的新文档项目，该项目将提示您一些问题。按下Enter接受所有默认值。

清单4.执行sphinx-quickstart

$ sphinx-quickstart 
Welcome to the Sphinx 1.0.5 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
[...]

我选择“我的项目”作为将在多个地方引用的项目名称。随意选择其他名称。

运行sphinx-quickstart命令之后，工作目录中应该有类似于清单5中的文件。

清单5.工作目录清单

.
├── Makefile
├── _build
├── _static
├── conf.py
└── index.rst

让我们仔细看看每个文件。

Makefile ：已编译代码的开发人员应熟悉此文件。如果不是，则将其视为包含使用make命令构建文档输出的说明的文件。
_build ：这是在触发特定输出后将放置生成文件的目录。
_static ：所有不属于源代码的文件（例如图像）都放在此处，然后在构建目录中链接在一起。
conf.py ：这是一个Python文件，其中包含Sphinx的配置值，包括在终端中执行sphinx-quickstart时选择的配置值。
index.rst ：文档项目的根。如果将文档拆分为其他文件，这将连接其他文件。

入门

至此，我们已经正确安装了Sphinx，了解了默认结构，并了解了一些基本语法。在跳入编写文档时要谨慎。缺乏有关布局和输出的知识可能会造成混乱，并可能大大减慢您的整个过程。

看一下index.rst 。有大量的信息和一些其他复杂的语法。为了使事情变得简单并避免分散注意力，我们将在主要部分列出新文件，以合并该文件。

在index.rst文件中主标题的index.rst ，有一个带有toctree声明的内容列表。 toctree是将所有文档收集到文档中的中心元素。如果存在其他文件，但未在此伪指令下列出，则在构建时不会与文档一起生成这些文件。

我们想在文档中添加一个新文件，它将被命名为example.rst 。它需要在toctree列出，但要小心。要使列表正常工作，必须遵循一个空格，并且不需要文件扩展名（在这种情况下为.rst ）。清单6显示了该列表的外观。需要使用三个空格将文件名与左边距分开，在maxdepth选项之后留一个空格。

清单6. index.rst中的toctree示例

Contents:

.. toctree::
   :maxdepth: 2

   example

此时，不必担心其他选项。现在，请注意，存在一个索引文件，其中列出了可以保存有效文档的其他单独文件，并且该清单遵循一定的顺序和间距。

还记得清单2中的示例语法吗？将该示例复制并粘贴到example.rst文件中并保存。现在我们准备生成输出。

运行make命令并指定HTML作为输出。此输出可以生成所有内容，包括JavaScript和CSS文件，因此可以直接用作网站。参见清单7 。

清单7. `make html`命令的输出

$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Making output directory...
Running Sphinx v1.0.5
loading pickled environment... not yet created
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index 
writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in _build/html.

如果您对make命令提供的其他选项感兴趣，请参见清单8 ，将help标志传递给它，并查看完整说明。

清单8.列出make选项

$ make -h
Usage: make [options] [target] ...
Options:
[...]

静态化

通过第一阶段从这两个文件生成HTML，我们有了一个功能齐全（静态）的网站。

在_build目录中，现在应该有两个新目录： doctrees和HTML 。我们对HTML目录感兴趣，该目录包含文档站点所需的所有文件。使用浏览器打开index.html文件应该显示如图1所示的内容。

图1.静态HTML主页

搜索部分很有趣，因为Sphinx已经索引了所有文件，并且使用JavaScript魔术创建了一个可搜索的静态站点。

还记得我们在清单6的toctree文档中将example作为一个单独的文件添加了吗？您可以看到主标题在内容索引中显示为主要项目符号，副标题为第二级项目符号。 Sphinx已采取一切适当的结构。

如果起初你没有成功...

进行其他修改后，只需再次运行make命令即可重新生成文件。

所有链接都将指向文档中的正确位置，并且标题和副标题具有允许直接链接的锚点。例如， Subject Subtitle部分包含一个锚点，该锚点在浏览器中看起来像../example.html#subject-subtitle 。如前所述，该工具消除了对这些微小的重复需求的担心。

图2显示了example.rst在静态站点中如何显示为HTML文件。

图2. HTML示例页面

走向图形

简短，简洁的段落，图像和图形都增加了项目文档的趣味性和可读性。 Sphinx可以帮助读者注意这些重要元素，并可以添加静态文件。

添加静态文件的正确语法很容易记住。只要将静态文件放置在Sphinx在创建文档布局时创建的_static目录中，您就可以毫无问题地引用它。在清单9中，查看该引用在reStructuredText文件中的外观。在这种情况下，我将其添加到example.rst的底部。

清单9. example.rst中的静态清单

.. image:: _static/system_activity.jpg

重新生成文档后，应将图像正确放置在我们指示有关系统活动的小JPEG图的路径的同一位置。它看起来应该类似于图3 。

图3.系统活动图像

结论

本文介绍了Sphinx入门的基本知识，但还有很多值得探索的地方。 Sphinx可以导出不同格式的文档，但是它们需要额外的库和软件来安装。可以生成的某些格式是：PDF，epub，man（UNIX手册页）和LaTeX。

对于复杂的图形，有一个插件可将Graphviz图形添加到您的文档项目中。我曾经不得不为一个小型办公室网络地图创建一个地图，这真是太好了，我可以不必使用其他工具就可以在同一文档中获取所有内容。像Graphviz插件一样，Sphinx有很多可用的插件（也称为扩展）。其中包括一些内容，例如interSphinx，它允许您链接不同的Sphinx项目。

如果生成的输出的外观不符合您的喜好，则Sphinx包含许多主题，可用于完全改变HTML文件渲染文档的方式。一些重要的开源项目，例如Celery和Lettuce，通过更改CSS并扩展模板来大量修改HTML的外观。请参阅相关主题的链接，这些项目和文件，说明如何扩展和修改默认CSS和布局部分。

Sphinx改变了我考虑编写文档的方式。当我能够轻松记录几乎所有的个人开放源代码项目和一些内部开放源代码项目时，我从无为而兴奋。使用Sphinx可以轻松地在您自己的文档中检索被遗忘的信息。

翻译自: https://www.ibm.com/developerworks/opensource/library/os-sphinx-documentation/index.html