使⽤Sphinx撰写技术⽂档并⽣成PDF总结
这⼏天准备编排部分翻译的书籍和⽂档,了好些⼯具,最终定格在 Sphinx 上,并基于 提供的 SaaS 服务进⾏分发和分享。本篇博客是对整个过程的⼀次记录和总结。
项⽬代码:
认识 Sphinx
是⼀个基于 Python 的⽂档⽣成项⽬。最早只是⽤来⽣成 的项⽬⽂档,使⽤ reStructuredText 格式。但随着项⽬的逐渐完善,很多⾮Python 的项⽬也采⽤ 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.
"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 [_]:
svg怎么转为pdfThe 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
/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 `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,整个设置过程包括:
1. 是否分离源⽂件⽬录 source 和⽣成⽂件⽬录 build,默认否;
2. 模板⽬录 templates 和静态⽂件⽬录 static 前缀,默认为_;
3. 项⽬名称;
4. 项⽬作者;
5. 项⽬版本,默认为空;
6. 项⽬语⾔,默认为 en;
7. ⽂档扩展名,默认为 .rst;
8. ⾸页⽂件名,默认为 index;
9. 开启的扩展,均默认为否:
1. autodoc
2. doctest
3. intersphinx
4. todo
5. coverage
6. imgmath
7. mathjax
8. ifconfig
9. viewcode
10. githubpages
10. ⽣成 Makefile,默认是;
11. ⽣成 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:⽂档项⽬起始⽂件。
接下来看看默认⽣成的内容:
Running Sphinx v1.8.4
loading translations [zh_CN]... done
making
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
[100%] index looking for none found done
done
done
[100%] index genindex
writing search
copying done
copying done
dumping search index in Chinese (code: zh) ... done
dumping 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'
第⼀个⽂档
我们以⼀下⽂档为例:
===============
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`
重新编译,这时⽂档已经改变。
版权声明:本站内容均来自互联网,仅供演示用,请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198,我们将在24小时内删除。
发表评论