综合技术

学习sphinx制作文档、编写书稿

微信扫一扫,分享到朋友圈

学习sphinx制作文档、编写书稿
0

学习sphinx制作文档

摘要

本篇中的sphinx不是开发搜索功能的软件,而是生成文档的工具。它使用reStructuredText编写文档,这是一种类似Markdown的简单标记语言。

比Markdown强大之处在于,它支持使用代码编写数学公式,使用代码制作流程图等图片,最后由sphinx解析成各种文件,比如HTML、PDF等。

所以,Markdown适合于单篇无体系的文章,而Sphinx更适合用于写作具有紧密联系的一些列文章,比如读书笔记、书稿等。

windows下使用sphinx

安装

安装 python

下载 python,下载地址: Windows x86-64 web-based installer

各版本解释

x86 适合 32 位操作系统,x86-64适合64位操作系统。

web-based installer 是需要通过联网完成安装的。我的理解是,下载的是一部分,全部安装包是

在启动此 installer 后,通过网络获取的。

executable installer 是可执行文件(*.exe)方式安装。下载下来的就是全部安装包。

embeddable zip file 嵌入式版本,可以集成到其它应用中。不理解。

下载安装包之后,直接双击安装。

安装 sphinx

打开CMD,执行命令

pip install Sphinx

CMD 窗口出现错误信息:

PermissionError: [WinError 5] 拒绝访问。: 'c:\program files\python35\Lib\site-packages\pytz'
You are using pip version 8.1.1, however version 8.1.2 is available.
You should consider upgrading via the 'python -m pip install --upgrade pip' command.

执行命令

python -m pip install --upgrade pip

仍然出现同样的错误。难道是用户权限问题。切换到管理员用户执行命令

python -m pip install --upgrade pip

屏幕打印信息

C:WINDOWSsystem32>python -m pip install --upgrade pip
Collecting pip
  Using cached pip-8.1.2-py2.py3-none-any.whl
Installing collected packages: pip
  Found existing installation: pip 8.1.1
    Uninstalling pip-8.1.1:
      Successfully uninstalled pip-8.1.1
Successfully installed pip-8.1.2

成功更新了pip。再回到普通用户执行安装 Sphinx 的命令

pip install Sphinx

屏幕打印信息的最后一部分

File "c:program filespython35libsite-packagespiputils__init__.py", line 83, in ensure_dir
    os.makedirs(path)
  File "c:program filespython35libos.py", line 241, in makedirs
    mkdir(name, mode)
PermissionError: [WinError 5] 拒绝访问。: 'c:\program files\python35\Lib\site-packages\colorama'

仍然是权限问题。在管理员CMD下再执行安装Sphinx命令

pip install Sphinx

屏幕打印信息最后一部分

Running setup.py install for MarkupSafe ... done
Successfully installed Jinja2-2.8 MarkupSafe-0.23 Pygments-2.1.3 Sphinx-1.4.6 
alabaster-0.7.9 babel-2.3.4 colorama-0.3.7 docutils-0.12 imagesize-0.7.1 pytz-2016.6.1 
six-1.10.0 snowballstemmer-1.2.1

安装sphinx成功了。

设置 the documentation sources

执行命令

sphinx-quickstart

运行结果如下图

学习sphinx制作文档_quickstart

根据需要回答它的一系列问题,对于 “autodoc” extension ,一定要回答 y

关于语言的回答,英文选择 en ,简体中文选择 zh_CN , 繁体中文选择 zh_TW

最后的运行结果是这样的

Creating file H:/sphinxsourceconf.py.
Creating file H:/sphinxsourceindex.rst.
Creating file H:/sphinxMakefile.
Creating file H:/sphinxmake.bat.

Finished: An initial directory structure has been created.

You should now populate your master file H:/sphinxsourceindex.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.

定义文档结构–Defining document structure

编译文档 – Running the build

执行命令

sphinx-build -b html sourcedir builddir

这条命令不能直接执行,需根据自己的需要修改。

-b ,选择需要的编译器,即要编译成什么格式的文件。

sourcedir ,要编译的源文件路径。必须设置。

builddir ,编译后的文件输出的路径。必须设置。

执行命令

sphinx-build -b html H:/sphinx/source H:/sphinx/build

执行成功后,以前为空的 H:/sphinx/build 目录下面出现了很多文件。

.
├── Makefile
├── build
├── source
└── make.bat
  1. Makefile:它是一个包含指令的文件,在使用 make 命令时,可以使用这些指令来构建文档输出。
  2. build:这是触发特定输出后用来存放所生成的文件的目录。
  3. source:源代码目录。
  4. make.bat:使用 make html 可以取代 sphinx-build -b html

参考资料

First steps with Sphinx

sphinx安装和基本操作

使用 sphinx 制作简洁而又美观的文档

阅读原文...


简书

Hexo 博客补丁

上一篇

Hackage reliability via mirroring

下一篇

您也可能喜欢

评论已经被关闭。

插入图片
学习sphinx制作文档、编写书稿

长按储存图像,分享给朋友