内容简介:这几天准备编排部分翻译的书籍和文档,找了好些工具,最终定格在 Sphinx 上,并基于项目代码:
这几天准备编排部分翻译的书籍和文档,找了好些工具,最终定格在 Sphinx 上,并基于 ReadTheDocs 提供的 SaaS 服务进行分发和分享。本篇博客是对整个过程的一次记录和总结。
项目代码: qiwihui/sphinx-doc-starter
认识 Sphinx
Sphinx 是一个基于 Python 的文档生成项目。最早只是用来生成 Python 的项目文档,使用 reStructuredText 格式。但随着项目的逐渐完善,很多非 Python 的项目也采用 Sphinx 作为文档写作工具,甚至完全可以用 Sphinx 来写书。
使用 Sphinx 生成文档的优点 包括:
- 丰富的输出格式 : 支持输出为 HTML(包括 Windows 帮助文档),LaTeX(可以打印PDF版本), manual pages(man 文档), 纯文本等若干种格式;
- 完备的交叉引用 : 语义化的标签,并可以自动化链接函数、类、引文、术语等;
- 明晰的分层结构 : 轻松定义文档树,并自动化链接同级/父级/下级文章;
- 美观的自动索引 : 可自动生成美观的模块索引;
- 精确的语法高亮 : 基于 Pygments 自动生成语法高亮;
- 开放的扩展 : 支持代码块的自动测试,自动包含 Python 的模块自述文档,等等。
开始
这个过程包括如下步骤:
- 安装 Sphinx
- 第一个文档
- 在线托管
- 生成 PDF
安装 Sphinx
Sphinx 依赖于 Python,并提供了 Python 包,所以使用 pip 安装既可。这里我只安装了 sphinx-doc
这个包。
pip install sphinx-doc
这时,通过 bash 自动补全(连续两下 tab
),可以看到有几个命令,Sphinx 推荐使用 sphinx-quickstart
,这是一个设置向导。
$ sphinx- sphinx-apidoc sphinx-autogen sphinx-build sphinx-quickstart
设置 Sphinx
运行 sphinx-quickstart
,以下主要设置项目名称,作者名称以及语言( zh_CN
)即可,其他默认。
$ sphinx-quickstart Welcome to the Sphinx 1.8.4 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Selected root path: . You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n) [n]: y Inside the root directory, two more directories will be created; "_templates" for custom HTML templates and "_static" for custom stylesheets and other static files. You can enter another prefix (such as ".") to replace the underscore. > Name prefix for templates and static dir [_]: The project name will occur in several places in the built documentation. > Project name: 一本书 > Author name(s): qiwihui > Project release []: 0.0.1 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. > Project language [en]: zh_CN The file name suffix for source files. Commonly, this is either ".txt" or ".rst". Only files with this suffix are considered documents. > Source file suffix [.rst]: One document is special in that it is considered the top node of the "contents tree", that is, it is the root of the hierarchical structure of the documents. Normally, this is "index", but if your "index" document is a custom template, you can also set this to another filename. > Name of your master document (without suffix) [index]: Indicate which of the following Sphinx extensions should be enabled: > autodoc: automatically insert docstrings from modules (y/n) [n]: > doctest: automatically test code snippets in doctest blocks (y/n) [n]: > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: > coverage: checks for documentation coverage (y/n) [n]: > imgmath: include math, rendered as PNG or SVG images (y/n) [n]: > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: > ifconfig: conditional inclusion of content based on config values (y/n) [n]: > viewcode: include links to the source code of documented Python objects (y/n) [n]: > githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html` instead of invoking sphinx-build directly. > Create Makefile? (y/n) [y]: > Create Windows command file? (y/n) [y]: Creating file ./source/conf.py. Creating file ./source/index.rst. Creating file ./Makefile. Creating file ./make.bat. Finished: An initial directory structure has been created. You should now populate your master file ./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.
解释1,整个设置过程包括:
- 是否分离源文件目录
source
和生成文件目录build
,默认否; - 模板目录
templates
和静态文件目录static
前缀,默认为_
; - 项目名称;
- 项目作者;
- 项目版本,默认为空;
- 项目语言,默认为
en
; - 文档扩展名,默认为
.rst
; - 首页文件名,默认为
index
; -
开启的扩展,均默认为否:
- autodoc
- doctest
- intersphinx
- todo
- coverage
- imgmath
- mathjax
- ifconfig
- viewcode
- githubpages
- 生成 Makefile,默认是;
- 生成 Windows 用命令行,默认是。
解释2,项目目录文件结构如下:
sphinx-test ├── Makefile ├── build ├── make.bat └── source ├── _static ├── _templates ├── conf.py └── index.rst
其中:
-
Makefile
:可以看作是一个包含指令的文件,在使用 make 命令时,可以使用这些指令来构建文档输出。 -
build
:生成的文件的输出目录。 -
make.bat
:Windows 用命令行。 -
_static
:静态文件目录,比如图片等。 -
_templates
:模板目录。 -
conf.py
:存放 Sphinx 的配置,包括在sphinx-quickstart
时选中的那些值,可以自行定义其他的值。 -
index.rst
:文档项目起始文件。
接下来看看默认生成的内容:
$ make html Running Sphinx v1.8.4 loading translations [zh_CN]... done making output directory... building [mo]: targets for 0 po files that are out of date building [html]: targets for 1 source files that are out of date updating environment: 1 added, 0 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index generating indices... genindex writing additional pages... search copying static files... done copying extra files... done dumping search index in Chinese (code: zh) ... done dumping object inventory... done build succeeded. The HTML pages are in build/html.
然后直接在浏览器中打开 build/html/index.html
这个文件。
默认风格为 alabaster
,可以改成 ReadTheDocs 的风格: sphinx_rtd_theme
。
# -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = 'sphinx_rtd_theme'
第一个文档
我们以一下文档为例:
This is a Title =============== That has a paragraph about a main subject and is set when the '=' is at least the same length of the title itself. Subject Subtitle ---------------- Subtitles are set with '-' and are required to have the same length of the subtitle itself, just like titles. Lists can be unnumbered like: * Item Foo * Item Bar Or automatically numbered: #. Item 1 #. Item 2 Inline Markup ------------- Words can have *emphasis in italics* or be **bold** and you can define code samples with back quotes, like when you talk about a command: ``sudo`` gives you super user powers!
将之写入 example.rst
中,并修改 index.rst
为:
Welcome to 一本书's documentation! ================================== .. toctree:: :maxdepth: 2 :caption: 目录: example Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`
重新编译,这时文档已经改变。
在线托管
ReadTheDocs 可是直接用于托管 sphinx 生成的网页文档。
将之前的文档用 Git 管理,并推送到 Github,然后在 ReadTheDocs 中 Import a Project
即可。
另外,可以设置自定义域名:
- 在域名管理中添加 DNS 的 CNAME 记录到
readthedocs.io
,比如onebook.qiwihui.com
- 在项目的
Admin
->Domains
中设置上一步添加的域名,开启 HTTPS,保存即可。
过程很简单。
生成 PDF
Sphinx 生成 PDF 的过程先将 rst 转换为 tex,再生产PDF。这个过程遇到了比较多的坑,最后总结下来过程如下:
首先,安装 Tex 环境。在 Mac 上,推荐安装 MacTex
而不是 BasicTex
,对于新手来说 BasicTex 上需要自己处理很多以来问题。完成后使用 tlmgr
更新 TexLive。
$ brew cask install mactex $ sudo tlmgr update --self
然后,在 con.py 中设置 latex_engine
和 latex_elements
两个参数,同时也可以设置 latex_documents
参数来设置文档。
latex_engine = 'xelatex' latex_elements = { 'papersize': 'a4paper', 'pointsize': '11pt', 'preamble': r''' \usepackage{xeCJK} \setCJKmainfont[BoldFont=STZhongsong, ItalicFont=STKaiti]{STSong} \setCJKsansfont[BoldFont=STHeiti]{STXihei} \setCJKmonofont{STFangsong} \XeTeXlinebreaklocale "zh" \XeTeXlinebreakskip = 0pt plus 1pt \parindent 2em \definecolor{VerbatimColor}{rgb}{0.95,0.95,0.95} \setcounter{tocdepth}{3} \renewcommand\familydefault{\ttdefault} \renewcommand\CJKfamilydefault{\CJKrmdefault} ''' } # 设置文档 latex_documents = [ (master_doc, 'sphinx.tex', '你的第一本 Sphinx 书', '作者:qiwihui', 'manual', True), ]
最后,编译:
$ make latexpdf
make latexpdf
会完成 rst转换为 tex 并将 tex 生成 PDF,可以手动分开:
$ make latex $ cd build/latex $ make
在 build/latex
下可以查看到生成的 PDF 文档。
字体
使用 fc-list
来获取字体信息,修改相应字体设置即可。
$ brew install fontconfig $ fc-list :lang=zh
遇到的问题:
- 遇到
"! LaTeX Error: File '*.sty' not found."
类的问题:
解决:使用 sudo tlmgr install
安装相应的包即可。
总结
简单过了一下整个文档的流程,总体来说,Sphinx非常适合用来编写项目文档,reStructuredText 比起 Markdown 也有太多的优势,值得推荐。
以上所述就是小编给大家介绍的《使用 Sphinx 撰写技术文档并生成 PDF 总结》,希望对大家有所帮助,如果大家有任何疑问请给我留言,小编会及时回复大家的。在此也非常感谢大家对 码农网 的支持!
猜你喜欢:- 如何撰写技术文档
- 以 Markdown 撰写文稿,以 LaTeX 排版
- Python数据抓取(2) —简单网络爬虫的撰写
- 软件测试人员如何撰写简历才能提高面试邀约率?
- 技术文档写作的道与术
- ShowDoc 2.8.3 发布,IT 团队的在线 API 文档、技术文档工具
本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们。
ASP.NET网页制作教程
王国荣 / 华中科技 / 2002-1 / 78.00元
《ASP.NET网页制作教程:从基本语法学起(附光盘)》分为:基础篇、对象应用篇、案例研究篇。奠定ASP网页制作的基础,使用Server控件制作互动网页,使用ADO.NET访问数据库;计费网费、会员管理、访客计数器Server版、访客留言板、新闻讨论群组、电子贺卡、E-mail自动传送、FIP文件上传、在线投票、在线问卷调查、在线购物、在线考试、广告回旋板、聊天室。一起来看看 《ASP.NET网页制作教程》 这本书的介绍吧!