查看“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']
然后

==HTML 主题==
Sphinx支持通过主题（themes）改变HTML输出的外观。
{{了解更多
|[https://www.sphinx-doc.org/zh_CN/master/usage/theming.html Sphinx文档：HTML 主题]
}}
===使用主题===

===常见主题===
{| class="wikitable"  style="width: 100%;
! 主题
! 描述
! 网址
|-
| pydata-sphinx-theme
| 基于[[Bootstrap]] 4，使用该主题的一些文档： <br \>[https://pandas.pydata.org/docs/ Pandas 文档]  <br \>[https://numpy.org/devdocs/ NumPy 文档]  <br \>[https://megengine.org.cn/doc/stable/zh/ MegEngine 文档]  <br \><br \>安装：<br \>1. 使用pip安装主题 <code>pip install pydata-sphinx-theme</code> <br \>2. 在conf.py中设置 <code>html_theme = "pydata_sphinx_theme"</code>
| 源代码：https://github.com/pydata/pydata-sphinx-theme  <br \>示例：https://pydata-sphinx-theme.readthedocs.io/en/latest/
|-
|sphinx-rtd-theme 
|Read the Docs Sphinx Theme <br \><br \>安装：<br \>1. 使用pip安装主题 <code>pip install sphinx-rtd-theme</code> <br \>2. 在conf.py中设置 <code>html_theme = "sphinx_rtd_theme"</code>
| https://github.com/readthedocs/sphinx_rtd_theme
|-
| 
| 
| 
|}

===制作主题===

{{了解更多
|[https://www.sphinx-doc.org/zh_CN/master/development/theming.html Sphinx文档：HTML 主题开发]
}}

==资源==
===官网===
*[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://zh.wikipedia.org/wiki/Sphinx_(文档生成器) 维基百科：Sphinx (文档生成器)]
*[https://www.ibm.com/developerworks/cn/opensource/os-sphinx-documentation/ IBM Developer：Alfredo Deza-使用 sphinx 制作简洁而又美观的文档]
*[https://www.neteye-blog.com/2021/04/how-to-create-a-custom-sphinx-theme/ NetEye: How to Create a Custom Sphinx Theme]
*[https://www.neteye-blog.com/2021/04/advanced-sphinx-theme-customization/ NetEye: Advanced Sphinx Theme Customization]


[[分类:编程工具]]