Metadata-Version: 2.1
Name: rst2html5
Version: 1.9.5
Summary: Generates (X)HTML5 documents from standalone reStructuredText sources
Home-page: https://bitbucket.org/andre_felipe_dias/rst2html5
Author: André Felipe Dias
Author-email: andref.dias@gmail.com
License: MIT License
Keywords: restructuredtext,rst,html5,doctutils
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Documentation
Classifier: Topic :: Utilities
Classifier: Topic :: Text Processing :: Markup :: HTML
License-File: LICENSE
License-File: AUTHORS.rst

=========
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
:code:`<section>` and :code:`<aside>`.


Installation
============

.. code-block:: bash

    $ pip install rst2html5


Usage
=====

.. code-block:: bash

	$ 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:

.. code-block:: rst

    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:

.. code-block:: html

    <!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 classes are spread over the html5 by default.
However stylesheets and javascripts URLs or paths can be included through ``stylesheet`` and ``script`` options:

.. parsed-literal::

    $ 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``


.. code-block:: html

    <!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>
    ...

Additional scripts can be included in the result
using options ``--script``, ``--script-defer`` or ``--script-async``:

.. parsed-literal::

    $ rst2html5 example.rst \\
        **--script** js/test1.js \\
        **--script-defer** js/test2.js \\
        **--script-async** js/test3.js

.. code-block:: html

    <!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:

.. parsed-literal::

    $ rst2html5 **--html-tag-attr** 'lang="pt-BR"' example.rst

.. code-block:: html

    <!DOCTYPE html>
    <html lang="pt-BR">
    ...


Templates
---------

Custom html5 template via the :literal:`--template` option. Example:

.. parsed-literal::

    $ 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

.. code-block:: html

    <!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
--------------

:code:`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:

.. code-block:: rst

    .. 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:

.. code-block:: rst

    .. 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:

.. code-block:: rst

    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


.. code-block:: html

    <!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 :code:`template` directive. The usage is:

.. code-block:: rst

    .. template:: filename

    or

    .. template::

        template content here.


Links
=====

* `Documentation <https://rst2html5.readthedocs.org/>`_
* `Project page at BitBucket <https://bitbucket.org/andre_felipe_dias/rst2html5>`_

=========
Changelog
=========

Here you can see the full list of changes between each rst2html5 releases.

* 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 :code:`stylesheet`, :code:`script` and :code:`template`
      for declaring stylesheets, scripts and template inside a restructured text.

* 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 :code:`define`, :code:`undef`, :code:`ifdef` and :code:`ifndef`
      to conditionally include (or not) a rst snippet.

* 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. :literal:`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 :literal:`: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


