python 3.x 安装 sphinx

前文中,介绍过 Sphinx 项目初始化配置介绍,原内容介绍的是,旧版的,今天介绍下新版的安装使用方法。(旧版是基于 python 2.x,新版是基于 python 3.x的)

基于 python 3.x 的 sphinx 配置项减少了很多,整体上一样。

在开始之前,先从 https://www.python.org/downloads/ 下载合适的版本,如 python-3.7.3 64位,
在安装时,留意勾选“Add Python 3.7 to PATH”,即将 Python 路径加入系统环境变量中。

1、查看 python 版本
在命令行中输入 python -V,显示版本信息,表明安装成功。
C:\Users\Admin>python -V
Python 3.7.3

2、查看 pip 版本
查看 pip 版本
C:\Users\Admin>pip -V
pip 19.0.3 from d:\python37\lib\site-packages\pip (python 3.7)

如果提示 找不到 python27.dll 表明,你电脑中有旧版 python,你需要卸载它。
并且检查系统环境变量中,是否存在 python27版本的环境变量并移除它。

3、安装 sphinx
留意从官方下载包会很慢,可以从国内镜像下载,
如 阿里云

让python pip使用国内镜像
C:\Users\Admin>pip install -i https://mirrors.aliyun.com/pypi/simple/ -U sphinx
之后,将开始远程下载并安装。

Installing collected packages: sphinxcontrib-serializinghtml, colorama, sphinxcontrib-devhelp, sphinxcontrib-htmlhelp, docutils, six, pyparsing, packaging, MarkupSafe, Jinja2, sphinxcontrib-jsmath, snowballstemmer, pytz, babel, sphinxcontrib-applehelp, urllib3, chardet, idna, certifi, requests, Pygments, sphinxcontrib-qthelp, imagesize, alabaster, sphinx

提示以上,表明安装成功。

4、查看 sphinx 版本
C:\Users\Admin>sphinx-build --version
sphinx-build 2.0.1

5、安装 主题
所有主题在: https://sphinx-themes.org/
通过下面的命令安装
pip install -i https://mirrors.aliyun.com/pypi/simple/ sphinx_rtd_theme

6、初始化项目
d:\doc>sphinx-quickstart

欢迎使用 Sphinx 2.0.1 快速创建工具。
请输入设置的值(如果括号号给出默认值,则按回车键使用默认值)

选择根目录:.

有2个选项可以放置 Sphinx 输出的构建目录。
要么在根路径中使用 “_build”,要么分离成“source” 和 “build”目录。

分离源目录和构建目录吗?(y/n)

The project name will occur in several places in the built documentation.
Project name:

项目名称将出现在文档中的多个位置。
项目名称:

Author name(s):
作者姓名:

Project release []:
项目发布版本:

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.

如果文档要用除英文以外的语言,
你可以通过设置语言代码,之后,Sphinx 将会翻译内容到该语言。

有关支持的代码列表,请参见:
http://sphinx-doc.org/config.html#confval-language

Finished: An initial directory structure has been created.

You should now populate your master file .\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where “builder” is one of the supported builders, e.g. html, latex or linkcheck.

完成:已经创建初始目录结构。
你可以应该编写主文件 .\index.rst 并创建其它文档。使用 Makefile 构建文档。

make <类型>
其中,类型是受支持构建器之一,如 html、latex 或 linkcheck。

进阶文档 手册 安装和 rst 语法 入门 pandoc 文档转换 CHM 其他