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>.
Installation
$ pip install rst2html5
Usage
$ rst2html5 [options] SOURCE
Options:
| --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) |
Example
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>
Stylesheets and Scripts
No stylesheets or scripts 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 https://example.com/css/default.css \ --stylesheet-inline css/simple.css \ --script https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js --script-defer js/test1.js --script-async js/test2.js
<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <link rel="stylesheet" href="https://example.com/css/default.css" /> <style>h1 {font-size: 20em} img.icon { width: 48px; height: 48px; } h2 {color: red} </style> <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script> <script src="js/test1.js" defer="defer"></script> <script src="js/test2.js" async="async"></script> </head> ...
Alternatively, you could specify stylesheets and scripts using directives in the 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 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"> ...
Templates
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>
New Directives
rst2html5 provides some new directives: define, undef, ifdef and ifndef,
similar to those used in C++.
They allow to conditionally include (or not) some rst snippets:
.. ifdef:: x this line will be included if 'x' was previously defined
In case of you check two or more identifiers, there must be an operator ([and | or]) defined:
.. ifdef:: x y z :operator: or This line will be included only if 'x', 'y' or 'z' is defined.
From rst2html5 1.9, you can include stylesheets and scripts via directives inside a reStructuredText text:
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> <meta charset="utf-8" /> <link href="css/default.css" rel="stylesheet" /> <link href="https://pronus.io/css/standard.css" rel="stylesheet" /> <script src="http://code.jquery.com/jquery-latest.min.js"></script> <script src="slide.js" defer="defer"></script> <script src="test/animations.js" async="async"></script> </head> <body> <p>Just an ordinary paragraph.</p> <p>Another paragraph</p> </body> </html>
There also is a template directive. The usage is:
.. template:: filename or .. template:: template content here.
Changelog
1.10.6 - 2020-04-21
- Contributing instructions updated.
1.10.5 - 2020-04-13
- rst2html5 is now hosted on Heptapod at https://foss.heptapod.net/doc-utils/rst2html5
1.10.4 - 2020-03-25
- Fix Pygments dependency
1.10.3 - 2020-03-14
- Fix KeyError: ‘refid’
1.10.2 - 2019-03-16
- Add missing ‘inline’ option for stylesheet directive
1.10.1 - 2018-12-02
- 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-06-19
- Documentation update
- Minor bug fixes
1.9.3 - 2017-02-14
- Fix setup.py
1.9.2 - 2017-02-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-07-12
- CodeBlock directive refactored
1.8.1 - 2016-07-11
- Raw html shouldn’t be indented
- CodeBlock directive also registered as code
1.8 - 2016-06-04
- New directives
define,undef,ifdefandifndefto conditionally include (or not) a rst snippet.
- New directives
1.7.5 - 2015-05-14
- fixes the stripping of leading whitespace from the highlighted code
1.7.4 - 2015-04-09
- fixes deleted blank lines in <table><pre> during Genshi rendering
- Testing does not depend on ordered tag attributes anymore
1.7.3 - 2015-04-04
- fix some imports
- Sphinx dependency removed
1.7.2 - 2015-03-31
- Another small bugfix related to imports
1.7.1 - 2015-03-31
- Fix 1.7 package installation. requirements.txt was missing
1.7 - 2015-03-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-03-09
- code-block’s :class: 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-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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
| Filename, size | File type | Python version | Upload date | Hashes |
|---|---|---|---|---|
| Filename, size rst2html5-1.10.6-py2.py3-none-any.whl (19.4 kB) | File type Wheel | Python version py2.py3 | Upload date | Hashes View |
Close
Hashes for rst2html5-1.10.6-py2.py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 8e64e80c52d0383aa04f2701a7627c2f2a09d59c61a3dc3555d845333bc31648 |
|
| MD5 | 3d587015dcef112136d15e080a1fe120 |
|
| BLAKE2-256 | 253a53db05fa09025139297989621124bbfd2e50712b68bb71619a30995c285a |
