Generates (X)HTML5 documents from standalone reStructuredText sources
Project description
rst2html5
rst2html5 generates (X)HTML5 documents from standalone reStructuredText sources. It is a complete rewrite of the docutils’ rst2html and uses new HTML5 constructs such as <section> and <aside>.
Usage
$ rst2html5 [options] SOURCEOptions:
- --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.
Examples
Consider the following rst snippet:
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/>`_The html5 produced is clean and tidy:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
</head>
<body>
<section id="title">
<h1>Title</h1>
<p>Some text and a target to <a href="#title-2">Title 2</a>. <strong>strong emphasis</strong>:</p>
<ul>
<li>item 1</li>
<li>item 2</li>
</ul>
</section>
<section id="title-2">
<h1>Title 2</h1>
<pre>Inline markup is supported, e.g. <em>emphasis</em>, <strong>strong</strong>, <code>literal
text</code>,
<a id="hyperlink-targets">hyperlink targets</a>, and <a href="http://www.python.org/">references</a></pre>
</section>
</body>
</html>No stylesheets or classes are spread over the html5 by default. However:
Stylesheets and javascripts URLs or paths can be included through stylesheet and script options.
$ rst2html5 example.rst \ --stylesheet css/default.css \ --stylesheet css/special.css \ --script https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <link href="css/default.css" rel="stylesheet" /> <link href="css/special.css" rel="stylesheet" /> <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script> ...Script attributes defer and async:
$ rst2html5 example.rst \ --script js/test1.js \ --script-defer js/test2.js \ --script-async js/test3.js
<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <script src="js/test1.js"></script> <script src="js/test2.js" defer="defer"></script> <script src="js/test3.js" async="async"></script> ...Html tag attributes can be included through html-tag-attr option:
$ rst2html5 --html-tag-attr 'lang="pt-BR"' example.rst
<!DOCTYPE html> <html lang="pt-BR"> ...Classes can be explicitly associated to rst elements (see ref):
.. class:: special This is a "special" paragraph. .. class:: exceptional remarkable An Exceptional Section ====================== This is an ordinary paragraph.which results in:
<p class="special">This is a "special" paragraph.</p> <section class="exceptional remarkable" id="an-exceptional-section"> <h1>An Exceptional Section</h1> <p>This is an ordinary paragraph.</p> </section>Custom html5 template via the --template option. Example:
$ 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> <meta charset="utf-8" /> <!-- 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> <p>one line</p> </body> </html>
Installation
$ pip install rst2html5Links
rst2html5 Changelog
Here you can see the full list of changes between each rst2html5 releases.
1.5 - 2015-23-02
rst2html5 generates html5 comments
A few documentation improvementss
1.4 - 2014-09-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-04-21
Fixes #16 | New –template option
runtests.sh without parameter should keep current virtualenv
1.2 - 2014-02-16
Fix doc version
1.1 - 2014-02-16
rst2html5 works with docutils 0.11 and Genshi 0.7
1.0 - 2013-06-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-05-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
