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

学习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:\WINDOWS\system32>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 files\python35\lib\site-packages\pip\utils\__init__.py", line 83, in ensure_dir
    os.makedirs(path)
  File "c:\program files\python35\lib\os.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:/sphinx\source\conf.py.
Creating file H:/sphinx\source\index.rst.
Creating file H:/sphinx\Makefile.
Creating file H:/sphinx\make.bat.

Finished: An initial directory structure has been created.

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

定义文档结构--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 制作简洁而又美观的文档

推荐阅读更多精彩内容

  • Ubuntu的发音 Ubuntu,源于非洲祖鲁人和科萨人的语言,发作 oo-boon-too 的音。了解发音是有意...
    萤火虫de梦阅读 57,000评论 12 420
  • Android 自定义View的各种姿势1 Activity的显示之ViewRootImpl详解 Activity...
    passiontim阅读 131,802评论 20 559
  • linux资料总章2.1 1.0写的不好抱歉 但是2.0已经改了很多 但是错误还是无法避免 以后资料会慢慢更新 大...
    O感悟人生O阅读 7,643评论 2 27
  • Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具(例如配置管理,服务发现,断路器,智...
    卡卡罗2017阅读 79,533评论 12 120
  • 随着生活水平的提高,消费者越来越关注饮食的营养和健康,已经实现从“有油吃”到“吃好油”的转变,众多消费者开始尝试高...
    李家铭先生阅读 95评论 0 0