从独立的structuredText源生成（x）HTML5文档
rst2html5的Python项目详细描述
rst2html5
rst2html5从独立的structuredtext源生成（x）html5文档。
它完全重写了docutils'rst2html并使用了新的html5结构，如
<section>和<aside>。
安装
$ pip install rst2html5
使用量
$ rst2html5 [options] SOURCE
选项：
| --no-indent | Don’t indent output |
| --stylesheet=<URL or path> | |
| Specify a stylesheet URL to be included. (This option can be used multiple times) | |
| --script=<URL or path> | |
| Specify a script URL to be included. (This option can be used multiple times) | |
| --script-defer=<URL or path> | |
| Specify a script URL with a defer attribute to be included in the output HTML file. (This option can be used multiple times) | |
| --script-async=<URL or path> | |
| Specify a script URL with a async attribute to be included in the output HTML file. (This option can be used multiple times) | |
| --html-tag-attr=<attribute> | |
| Specify a html tag attribute. (This option can be used multiple times) | |
| --template=<filename or text> | |
| Specify a filename or text to be used as the HTML5 output template. The template must have the {head} and {body} placeholders. The “<html{html_attr}>” placeholder is recommended. | |
| --define=<identifier> | |
| Define a case insensitive identifier to be used with ifdef and ifndef directives. There is no value associated with an identifier. (This option can be used multiple times) |
示例
请考虑以下第一个片段：
Title===== Some text and a target to `Title 2`_. **strong emphasis**: * item 1 * item 2 Title 2=======..parsed-literal:: Inline markup is supported, e.g. *emphasis*, **strong**, ``literal text``, _`hyperlink targets`, and `references <http://www.python.org/>`_
生产的HTML5干净整洁：
<!DOCTYPE html><html><head><metacharset="utf-8"/></head><body><sectionid="title"><h1>Title</h1><p>Some text and a target to <ahref="#title-2">Title 2</a>. <strong>strong emphasis</strong>:</p><ul><li>item 1</li><li>item 2</li></ul></section><sectionid="title-2"><h1>Title 2</h1><pre>Inline markup is supported, e.g. <em>emphasis</em>, <strong>strong</strong>, <code>literal text</code>, <aid="hyperlink-targets">hyperlink targets</a>, and <ahref="http://www.python.org/">references</a></pre></section></body></html>
样式表和脚本
默认情况下，HTML5上没有样式表或脚本。 但是，样式表和javascripts url或路径可以通过stylesheet和script选项包括：
$ rst2html5 example.rst \ --stylesheethttps://example.com/css/default.css \ --stylesheet-inline css/simple.css \ --script ^{tt3}$ --script-defer ^{tt4}$ --script-async ^{tt5}$
<!DOCTYPE html><html><head><metacharset="utf-8"/><linkrel="stylesheet"href="https://example.com/css/default.css"/><style>h1{font-size:20em}img.icon{width:48px;height:48px;}h2{color:red}</style><scriptsrc="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script><scriptsrc="js/test1.js"defer="defer"></script><scriptsrc="js/test2.js"async="async"></script></head> ...
或者，可以使用rst中的指令指定样式表和脚本：
..stylesheet:: https://example.com/css/default.css ..stylesheet:: css/simple.css :inline:..script:: https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js ..script:: js/test1.js :defer:..script:: js/test2.js :async:Title=====...
HTML标记属性可以通过html-tag-attr选项：
$ rst2html5 --html-tag-attr 'lang="pt-BR"' example.rst
<!DOCTYPE html><htmllang="pt-BR"> ...
模板
通过--template选项自定义HTML5模板。示例：
$ template='<!DOCTYPE html>
<html{html_attr}>
<head>{head} <!-- custom links and scripts -->
<link href="css/default.css" rel="stylesheet" />
<link href="css/pygments.css" rel="stylesheet" />
<script src="http://code.jquery.com/jquery-latest.min.js"></script>
</head>
<body>{body}</body>
</html>'
$ echo 'one line' > example.rst
$ rst2html5 --template "$template" example.rst
<!DOCTYPE html><html><head><metacharset="utf-8"/><!-- custom links and scripts --><linkhref="css/default.css"rel="stylesheet"/><linkhref="css/pygments.css"rel="stylesheet"/><scriptsrc="http://code.jquery.com/jquery-latest.min.js"></script></head><body><p>one line</p></body></html>
新指令
rst2html5提供了一些新指令：define，undef，ifdef和ifndef，
类似于C++中使用的那些。
它们允许有条件地包括（或不包括）一些rst片段：
..ifdef:: x this line will be included if 'x' was previously defined
如果您检查了两个或多个标识符， 必须定义一个运算符（[and | or]）：
..ifdef:: x y z :operator:or This line will be included only if 'x', 'y' or 'z' is defined.
在rst2html5 1.9中，您可以在重构文本中通过指令包含样式表和脚本：
Just an ordinary paragraph. ..stylesheet:: css/default.css ..stylesheet:: https://pronus.io/css/standard.css ..script:: http://code.jquery.com/jquery-latest.min.js ..script:: slide.js :defer:..script:: test/animations.js :async: Another paragraph
<!DOCTYPE html><html><head><metacharset="utf-8"/><linkhref="css/default.css"rel="stylesheet"/><linkhref="https://pronus.io/css/standard.css"rel="stylesheet"/><scriptsrc="http://code.jquery.com/jquery-latest.min.js"></script><scriptsrc="slide.js"defer="defer"></script><scriptsrc="test/animations.js"async="async"></script></head><body><p>Just an ordinary paragraph.</p><p>Another paragraph</p></body></html>
还有一个template指令。用法是：
..template:: filename or ..template:: template content here.
更改日志
1.10.2-2019年3月16日
- Add missing ‘inline’ option for stylesheet directive
1.10.1-2018年12月2日
- fix: –stylesheet-inline must not escape html characters
- Update package dependency to Pygments >= 2.3.0
1.10-2018年11月29日
- Support –stylesheet-inline
1.9.5-2018-10-06
- Fix version exhibition
1.9.4-2018年6月19日
- Documentation update
- Minor bug fixes
1.9.3-2017年2月14日
- Fix setup.py
1.9.2-2017年2月14日
- Fix conflict with docutils==0.13.1 rst2html5.py
1.9.1-2017-02-07
- Fix install_requires in setup.py
- Update list of authors
1.9-2016年12月21日
- New directives
stylesheet,scriptandtemplatefor declaring stylesheets, scripts and template inside a restructured text.
- New directives
1.8.2-2016年7月12日
- CodeBlock directive refactored
1.8.1-2016年7月11日
- Raw html shouldn’t be indented
- ^{tt13}$ directive also registered as ^{tt14}$
1.8-2016-06-04
- New directives
define,undef,ifdefandifndefto conditionally include (or not) a rst snippet.
- New directives
1.7.5-2015年5月14日
- fixes the stripping of leading whitespace from the highlighted code
1.7.4-2015年4月9日
- fixes deleted blank lines in <table><pre> during Genshi rendering
- Testing does not depend on ordered tag attributes anymore
1.7.3-2015年4月4日
- fix some imports
- Sphinx dependency removed
1.7.2-2015年3月31日
- Another small bugfix related to imports
1.7.1-2015年3月31日
- Fix 1.7 package installation. ^{tt15}$ was missing
1.7-2015年3月31日
- Small bufix in setup.py
- LICENSE file added to the project
- Sublists are not under <blockquote> anymore
- Never a <p> as a <li> first child
- New CodeBlock directive merges docutils and sphinx CodeBlock directives
- Generated codeblock cleaned up to a more HTML5 style: <pre data-language=”…”>…</pre>
1.6-2015年3月9日
- code-block’s ^{tt16}$ value should go to <pre class=”value”> instead of <pre><code class=”value”>
- Fix problem with no files uploaded to Pypi in 1.5 version
1.5-2015-23-02
- rst2html5 generates html5 comments
- A few documentation improvementss
1.4-2014年9月21日
- Improved packaging
- Using tox for testing management
- Improved compatibility to Python3
- Respect initial_header_level_setting
- Container and compound directives map to div
- rst2html5 now process field_list nodes
- Additional tests
- Multiple-time options should be specified multiple times, not with commas
- Metatags are declared at the top of head
- Only one link to mathjax script is generated
1.3-2014年4月21日
- Fixes #16 | New –template option
- runtests.sh without parameter should keep current virtualenv
1.2-2014年2月16日
- Fix doc version
1.1-2014-02-16
- rst2html5 works with docutils 0.11 and Genshi 0.7
1.0-2013年6月17日
- Documentation improvement
- Added html-tag-attr, script-defer and script-async options
- Dropped option-limit option
- Fix bug with caption generation within table
- Footer should be at the bottom of the page
- Indent raw html
- field-limit and option-limit are set to 0 (no limit)
0.10-2013年5月11日
- Support docutils 0.10
- Force syntax_hightlight to ‘short’
- Conforming to PEP8 and PyFlakes
- Testing structure simplified
- rst2html5.py refactored
- Some bugfixes
0.9-2012-08-03
- First public preview release
欢迎加入QQ群-->： 979659372
