神刀安全网

学习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制作文档、编写书稿
学习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 制作简洁而又美观的文档

转载本站任何文章请注明:转载至神刀安全网,谢谢神刀安全网 » 学习sphinx制作文档、编写书稿

分享到:更多 ()

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址