Documentation/translations/zh_CN/doc-guide/sphinx.rst

Source file repositories/reference/linux-study-clean/Documentation/translations/zh_CN/doc-guide/sphinx.rst

File Facts

System
Linux kernel
Corpus path
Documentation/translations/zh_CN/doc-guide/sphinx.rst
Extension
.rst
Size
14082 bytes
Lines
413
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. include:: ../disclaimer-zh_CN.rst

:Original: Documentation/doc-guide/sphinx.rst

:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn>

.. _sphinxdoc_zh:

简介
====

Linux内核使用 `Sphinx <http://www.sphinx-doc.org/>`_ 来把 ``Documentation``
下的 `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ 文件转
换成漂亮的文档。使用 ``make htmldocs`` 或 ``make pdfdocs`` 命令即可构建HTML
或PDF格式的文档。生成的文档放在 ``Documentation/output`` 文件夹中。

reStructuredText文件可能包含包含来自源文件的结构化文档注释或kernel-doc注释。
通常它们用于描述代码的功能、类型和设计。kernel-doc注释有一些特殊的结构和
格式，但除此之外，它们还被作为reStructuredText处理。

最后，有成千上万的纯文本文档文件散布在 ``Documentation`` 里。随着时间推移，
其中一些可能会转换为reStructuredText，但其中大部分仍保持纯文本。

.. _sphinx_install_zh:

安装Sphinx
==========

Documentation/ 下的ReST文件现在使用sphinx1.7或更高版本构建。

这有一个脚本可以检查Sphinx的依赖项。更多详细信息见
:ref:`sphinx-pre-install_zh` 。

大多数发行版都附带了Sphinx，但是它的工具链比较脆弱，而且在您的机器上升级它
或其他一些Python包导致文档构建中断的情况并不少见。

避免此情况的一种方法是使用与发行版附带的不同的版本。因此，建议使用
``virtualenv-3`` 或 ``virtualenv`` 在虚拟环境中安装Sphinx，具体取决于发行版
如何打包Python3。

.. note::

   #) html输出建议使用RTD主题。根据Sphinx版本的不同，它应该用
      ``pip install sphinx_rtd_theme`` 单独安装。

   #) 一些ReST页面包含数学表达式。由于Sphinx的工作方式，这些表达式是使用 LaTeX
      编写的。它需要安装amsfonts和amsmath宏包，以便显示。

总之，如您要安装Sphinx 2.4.4版本，应执行::

       $ virtualenv sphinx_2.4.4
       $ . sphinx_2.4.4/bin/activate
       (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt

在运行 ``. sphinx_2.4.4/bin/activate`` 之后，提示符将变化，以指示您正在使用新
环境。如果您打开了一个新的shell，那么在构建文档之前，您需要重新运行此命令以再
次进入虚拟环境中。

图片输出
--------

内核文档构建系统包含一个扩展，可以处理GraphViz和SVG格式的图像（参见
:ref:`sphinx_kfigure_zh` ）。

为了让它工作，您需要同时安装GraphViz和ImageMagick包。如果没有安装这些软件包，
构建系统仍将构建文档，但不会在输出中包含任何图像。

PDF和LaTeX构建
--------------

Annotation

Implementation Notes