Sphinx制作htmlhelp手册文档(Manual-chm)

原创 2017年05月04日 10:19:54
  • 安装Sphinx
  1. www.python.org 下载python2|3并安装,目前都内置pip管理,将目录环境添加到path
  2. pip install sphinx 或者 https://pypi.python.org/pypi/Sphinx 可下载包

Sphinx Available builders

The builder’s “name” must be given to the -b command-line option ofsphinx-build to select a builder

class sphinx.builders.html.StandaloneHTMLBuilder

Its name is html.

class sphinx.builders.html.DirectoryHTMLBuilder

Its name is dirhtml.

class sphinx.builders.html.SingleFileHTMLBuilder

Its name is singlehtml.

class sphinx.builders.htmlhelp.HTMLHelpBuilder

Its name is htmlhelp.

class sphinx.builders.qthelp.QtHelpBuilder

Its name is qthelp.

class sphinx.builders.devhelp.DevhelpBuilder

Its name is devhelp.

class sphinx.builders.epub.EpubBuilder

Its name is epub.

class sphinx.builders.latex.LaTeXBuilder

Its name is latex.

class sphinx.builders.text.TextBuilder

Its name is text.

class sphinx.builders.manpage.ManualPageBuilder

Its name is man.

class sphinx.builders.texinfo.TexinfoBuilder

Its name is texinfo.

class sphinx.builders.html.SerializingHTMLBuilder

implementation

out_suffix

globalcontext_filename

searchindex_filename

class sphinx.builders.html.PickleHTMLBuilder

Its name is pickle

class sphinx.builders.html.JSONHTMLBuilder

Its name is json.

class sphinx.builders.gettext.MessageCatalogBuilder

Its name is gettext.

class sphinx.builders.changes.ChangesBuilder

Its name is changes.

class sphinx.builders.linkcheck.CheckExternalLinksBuilder

Its name is linkcheck.

详情:http://zh-sphinx-doc.readthedocs.io/en/latest/contents.html

===============

  • 命令行用法

sphinx-build 脚本构建了一个Sphinx文档集。用法如下:

$ sphinx-build [options] sourcedir builddir [filenames]

在这里,sourcedir 是指 源目录builddir 是指你想指定的生成文档的目录。大部分时候,是不需要指定 filenames

sphinx-build 脚本有如下的选项:

-b buildername

最重要的选项: 它选择生成器。常见的生成器如下:

html
生成HTML页面。这是默认生成器。
dirhtml
生成HTML页面,但是每个文件单独一个目录。如果web服务器提供服务,能够生成漂亮的URLs(没有 .html 后缀)。
singlehtml
整个内容生成一个HTML页面。
htmlhelp, qthelp, devhelp, epub
生成HTML文件,包含了生成上述格式的文档集合的其他信息。
latex
生成可以被编译成PDF文件的LaTeX源文件通过使用 pdflatex
man
生成UNIX操作系统的groff格式的手册。
texinfo
生成Texinfo文件,它能够通过 makeinfo 处理成 Info 文件。
text
生成纯文本文件。
gettext
生成gettext的风格的消息目录(.pot 后缀的文件)。
doctest
如果 doctest 激活,执行文件中所有的doctests。
linkcheck
检查所有的外部链接的完整性。

请参看 Available builders,里面列出了Sphinx自身附带的所有的生成器。用户可以添加自己的生成器扩展。

-a

如果给定,总是生成所有输出文件。默认是只生成新的和更改的源文件的输出文件。(这可能并不适用于所有的生成器。)

-E

不要使用已保存的 环境 (系统缓存所有交叉引用),会完全重新生成。默认是仅仅读取和解析自上次运行后新的或者已更新的源文件。

-t tag

定义标签 tag。这跟 only 指令(标识符)关系密切,如果设置标签就会只包含 only 指令(标识符)的内容。

New in version 0.6.

-d path

因为Sphinx在生成输出文件之前,必须读取和解析所有的源文件,被解析过的源文件会被缓存为”doctree pickles”。通常,这些缓存文件会被放入于生成目录中的名为 .doctrees 的文件夹里;使用该选项可以选择不同的缓存文件夹(所有生成器都可以共享doctrees文件夹)。

-c path

使用给定的配置文件目录,忽略源文件中的 conf.py 配置文件。值得注意的是配置文件中的其他文件以及路径可能会跟配置文件目录有关,所以也必须使用指定的路径。

New in version 0.3.

-C

不使用配置文件;使用 -D 选项后的配置值。

New in version 0.5.

-D setting=value

覆盖配置文件 conf.py 中一个配置值对。该值必须是一个字符串或者字典值。对于字典值,需要给吃键值对类似:-D latex_elements.docclass=scrartcl。对于布尔值,使用 0 或者 1

Changed in version 0.6: The value can now be a dictionary value.

-A name=value

在HTML模版中,把 value 赋给 name 

New in version 0.5.

-n

运行在严格模式。目前,这会对所有丢失的引用抛出警告。

-N

禁止带颜色的输出。(Windows下任何的带颜色的输出都是无效的。)

-q

不要在标准输出上输出任何东西,只给出标准错误的警告和错误。

-Q

不要在标准输出上输出任何东西,也包括警告。只有错误被写入标准错误。

-w file

输出除标准错误外的警告(和错误)到指定的文件。

-W

把警告转换成错误输出。这就说构建会在第一个警告的时候停止,sphinx-build 会以错误状态1退出。

-P

(仅调试时有用。)构建时候,如果出现未处理的遗产,运行python调试器,pdb

在命令行中,你可以在源目录以及生成目录后给出一个或者多个文件名。Sphinx 将会尝试构建给出的这些文件的输出(以及它们的依赖。)

Makefile选项

 sphinx-quickstart 生成的 Makefile  make.bat 文件是只使用了 sphinx-build  -b  -d 参数。 然而, 它们支持以下的变量(参数)来定制化:

PAPER

latex_paper_size 的值。

SPHINXBUILD

替代 sphinx-build 的命令。

BUILDDIR

指定生成的目录,而不是使用在 sphinx-quickstart 中选择的路径。

SPHINXOPTS

sphinx-build 的附加选项。

调用sphinx-apidoc

sphinx-apidoc 能够对一个python包生成完全的自动的API文档。调用它像这样:

$ sphinx-apidoc [options] -o outputdir packagedir [pathnames]

packagedir 是指生成文档的包所在的路径, outputdir 生成的文档所存放的路径。任何给定的 pathnames 是在生成过程中需要忽略的路径名([pathnames]里的东西在生成文档中是忽略的。)

sphinx-apidoc 有如下些选项:

-o outputdir

给出生成的文档所在的路径。

-f, --force

通常,sphinx-apidoc不会重新生成任何文件。使用这个选项强制重新生成所有的文件。

-n, --dry-run

使用这个选项的话,不会有任何文件生成。(空运行,或者称为干运行。)

-s suffix

这个选项指定了输出的文件的文件名后缀。默认情况下,后缀是 rst

-d maxdepth

如果存在内容表,设置内容表的最大深度。

-T, --no-toc

这可以防止生成的表的内容文件 modules.rst。但是当 --full 给出的时候,本选项就不起作用了。

-F, --full

此选项使得sphinx-apidoc创建一个完整的Sphinx项目,与 sphinx-quickstart 使用同样的机制。大部分的配置值是设置成默认的值,但是你可以通过如下选项修改一些重要的配置值。

-H project

设置项目名称,使得生成到输出的文件 (请见 project).

-A author

设置作者名,使得生成到输出的文件 (请见 copyright).

-V version

设置项目版本,使得生成到输出的文件 (请见 version).

-R release

设置项目发布,使得生成到输出的文件 (请见 release).

=================

  • 命令行 使用sphinx-quickstart 快速创建DOC项目

pass

  • make htmlhelp

即可在DOC内创建build/htmlhelp 的源文件,需要系统安装Microsoft HTML Help支持

Microsoft HTML Help Workshop https://msdn.microsoft.com/en-us/library/ms669985

同时生成  Microsoft的.chm文件

 

版权声明:本文为博主原创文章,未经博主允许不得转载。

Sphinx做全站搜索你会了木有?

本文主要介绍Sphinx的入门使用,新手观看,老鸟指正! * 1、简介 * 1.1.Sphinx是什么 * 1.2.Sphinx的特性 * 1.3.Sphinx中文分词 * 2、安装配置实例 ...
  • qq1355541448
  • qq1355541448
  • 2014年03月24日 17:21
  • 8327

sphinx 使用教程-挺简单易懂

使用打开控制台,必需打开控制台PHP才能连接到sphinx(确保你已经建立好索引源): d:\coreseek\bin\searchd -c d:\coreseek\bin\sphinx.con...
  • u014060400
  • u014060400
  • 2015年02月03日 16:35
  • 4942

用sphinx_doc编写API文档

用sphinx_doc 编写API文档
  • xubeiqiannian
  • xubeiqiannian
  • 2015年12月04日 15:19
  • 3562

Sphinx-doc编写文档

sphinx-doc是一种基于python的文档编写工具。python的官方帮助文档就是使用它编写的。sphinx-doc是reStructuredText,即使用带有简单语法的文本文件来编写文件,然...
  • weishantc
  • weishantc
  • 2015年07月02日 17:27
  • 3502

Linux下CHM查看工具汇总

 Linux下CHM查看工具汇总 http://www.ossw.com.cn/bbs/bencandy.php?id=2252&l_page=1 ...
  • jallin2001
  • jallin2001
  • 2009年11月11日 09:35
  • 1774

sphinx调用API参考(官方手册)

Sphnix有几种不同编程语言的searchd客户端API的实现。在本文完成之时,我们对我们自己的PHP,Python和java实现提供官方支持。此外,也有一些针对Perl,Ruby和C++的第三方免...
  • slqgenius
  • slqgenius
  • 2016年06月19日 21:34
  • 4296

sphinx帮助我通过rst生成静态html

windows下使用sphinx生成静态网页。官方教程,特详细 http://www.sphinx-doc.org/en/stable/tutorial.html 参考IBM https://w...
  • lineuman
  • lineuman
  • 2016年12月23日 22:51
  • 773

sphinx调用API参考(官方手册)

Sphnix有几种不同编程语言的searchd客户端API的实现。在本文完成之时,我们对我们自己的PHP,Python和java实现提供官方支持。此外,也有一些针对Perl,Ruby和C++的第三方免...
  • slqgenius
  • slqgenius
  • 2016年06月19日 21:34
  • 4296

使用sphinx生成美观的文档

先上效果图 详情 首先,需要知道什么是restructuredtext,可以理解为类似于markdown的一个东西。 然后 安装,pip install sphinx 进入存放文档的目录,在...
  • u010180339
  • u010180339
  • 2015年07月06日 21:00
  • 3349

Sphinx-doc编写文档

sphinx-doc是一种基于python的文档编写工具。python的官方帮助文档就是使用它编写的。sphinx-doc是reStructuredText,即使用带有简单语法的文本文件来编写文件,然...
  • weishantc
  • weishantc
  • 2015年07月02日 17:27
  • 3502
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:Sphinx制作htmlhelp手册文档(Manual-chm)
举报原因:
原因补充:

(最多只允许输入30个字)