查看“Sphinx”的源代码

Sphinx是用于创建文档的工具。它最初是为[[Python]]文档创建的，也可以在其他环境中使用。Sphinx使用 [[reStructuredText]] 作为标记语言，可输出格式包括[[HTML]]、[[LaTeX]]、[[PDF]]、[[ePub]]、Texinfo、man和纯文本等。  


==简介==
===时间轴===

===用户===
以下一些使用Sphinx工具的网站：
*[https://docs.python.org/zh-cn/3/ Python 文档]
*[https://pandas.pydata.org/pandas-docs/stable/ Pandas 文档]
*[https://flask.palletsprojects.com Flask 文档]

{{了解更多
|[https://www.sphinx-doc.org/zh_CN/master/examples.html 使用Sphinx的项目]
}}
==安装==
===使用pip安装===
Sphinx软件包发布在[[PyPI]]上，可以使用[[pip]]安装：
 pip install -U sphinx

===使用docker安装===
Sphinx的官方[[docker]]镜像有两个：
*[https://hub.docker.com/repository/docker/sphinxdoc/sphinx sphinxdoc/sphinx]，常用的Sphinx镜像。
*[https://hub.docker.com/repository/docker/sphinxdoc/sphinx-latexpdf sphinxdoc/sphinx-latexpdf]，比较大，主要使用LaTeX构建PDF的Sphinx镜像。
先安装好[[docker]]，使用以下命令来创建Sphinx项目：
 docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart

===Linux===
[[Debian]]/[[Ubuntu]]下安装python3-sphinx使用apt-get：
 apt-get install python3-sphinx
RHEL, CentOS下安装python3-sphinx使用yum：
 yum install python-sphinx

===使用源代码安装===
使用[[git]]从[[Github]]下载源代码，然后pip安装
 <nowiki>$ git clone https://github.com/sphinx-doc/sphinx
$ cd sphinx
$ pip install .</nowiki>

{{了解更多
|[https://www.sphinx-doc.org/en/master/usage/installation.html Sphinx文档：安装]
}}
==入门==
{{了解更多
|[https://www.sphinx-doc.org/en/master/usage/quickstart.html Sphinx文档-快速开始]
}}
===文档结构===
文档根目录下：
*source 目录：存放用[https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html reStructuredText]格式编写文档。
*conf.py 文件：Sphinx 配置文件。可以设置网页模板主题，启用某些插件，配置路径等。
可以通过脚本sphinx-quickstart来快速生成。创建一个文档目录，在终端进入该目录，然后运行下面命令：
 sphinx-quickstart
运行完后在文档目录下自动生成：
*source 目录：存放用[https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html reStructuredText]格式编写文档。
*conf.py 文件：Sphinx 配置文件。
*index.rst 文件：文档主页。
*make.bat 文件：生成静态网页。
*Makefile 文件：

===编写内容===
Sphinx支持大部分标准[https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html reStructuredText]语法，Sphinx还提供了一些特定的语法。

===生成网页===
当你添加了一些文件和内容，就可以生成网页了使用sphinx-build程序，如：
 sphinx-build -b html sourcedir builddir
如果你使用sphinx-quickstart快速生成的，可以直接使用make.bat来生成网页：
 make html
现在静态网页可以在_build目录下的html目录中，直接打开浏览即可。

===Autodoc===
使用python语言的项目编写文档时候，可以使用插件autodoc来自动提取源代码中的文档。在conf.py中输入如下内容以开启autodoc：
 extensions = ['sphinx.ext.autodoc']
然后


==资源==
===官网===
*[https://www.sphinx-doc.org/ Sphinx 官网]
*[https://www.sphinx-doc.org/en/master/contents.html Sphinx 文档：目录]
*[https://www.sphinx-doc.org/zh_CN/master/index.html Sphinx 中文官网]
*[https://www.sphinx-doc.org/zh_CN/master/contents.html Sphinx 中文文档：目录]
*[https://github.com/sphinx-doc/sphinx Sphinx 的 GitHub]

===相关网站===
*[https://www.ibm.com/developerworks/cn/opensource/os-sphinx-documentation/ IBM Developer：Alfredo Deza-使用 sphinx 制作简洁而又美观的文档]
*[https://www.biaodianfu.com/sphinx-documentation.html 标点符：使用Sphinx制作说明文档]

==参考文献==
*[https://zh.wikipedia.org/wiki/Sphinx_(文档生成器) 维基百科：Sphinx (文档生成器)]

[[分类:编程工具]]