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)
If ``DEST`` is not provided, the output is send to ``stdout``.
Example
-------
Consider a file called ``example.rst`` that contains:
.. 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 `_
The command to produce an ``example.html`` output file is::
$ rst2html5 example.rst example.html
The HTML5 produced is clean and tidy:
.. code-block:: html
Title
Some text and a target to Title 2 . strong emphasis :
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:
.. parsed-literal::
$ 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``
.. code-block:: html
...
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
...
Templates
---------
Custom HTML5 template via the :literal:`--template` option. Example:
.. parsed-literal::
$ template='
{head}
{body}
'
$ echo 'one line' > example.rst
$ rst2html5 **--template "$template"** example.rst
.. code-block:: html
one line
New Directives
==============
``define``, ``undef``, ``ifdef`` and ``ifndef``
-----------------------------------------------
: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.
``stylesheet`` and ``script``
-----------------------------
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
Just an ordinary paragraph.
Another paragraph
``template``
------------
There also is a :code:`template` directive. The usage is:
.. code-block:: rst
.. template:: filename
or
.. template::
template content here.
New Roles
=========
``:abbr:``
----------
From `MDN Web Docs `_:
The HTML Abbreviation element (:code:``) represents an abbreviation or acronym;
the optional title attribute can provide an expansion or description for the abbreviation.
If present, title must contain this full description and nothing else.
To create an abbreviation in ``rst2html5`` use the ``:abbr:`` role:
.. code:: rst
* :abbr:`SPA (Single-Page Application)`
* :abbr:`ASGI (Asynchronous Server Gateway Interface)` is a spiritual successor to :abbr:`WSGI`
* :abbr:`WSGI (Web Server Gateway Interface)`
Resulting in:
.. code:: html
SPA
ASGI
is a spiritual successor to
WSGI
WSGI
Note that if the abbreviation follows the pattern ``ABBR (Description for the abbreviation)``,
the description is extracted and becomes the ``title``.
How To Use rst2html5 Programmatically
=====================================
You should use ``rst2html5.HTML5Writer`` with one of the ``publish_*` methods available in ``docutils.core``.
In the case that the input and output will be in memory,
``publish_parts`` is the best fit:
.. code:: python
from docutils.core import publish_parts
from rst2html5 import HTML5Writer
text = r'''The area of a circle is :math:`A_\text{c} = (\pi/4) d^2`.
.. math::
\frac{ \sum_{t=0}^{N}f(t,k) }{N}
'''
body = publish_parts(writer=HTML5Writer(), source=text)['body']
print(body)
Resulting in:
.. code:: html
The area of a circle is
\(A_\text{c} = (\pi/4) d^2\)
.
\(\frac{ \sum_{t=0}^{N}f(t,k) }{N}\)
.. attention::
Version 2.0 renames the module ``rst2html5_`` back to ``rst2html5``
since the conflict with docutils installation is solved.
Importing ``rst2html5_.HTML5Writer`` still works though.
See the section "**Workaround to Conflicts with Docutils**"
on ``docs/design_notes.rst`` for more information.
See also: `The Docutils Publisher `_
Links
=====
* `Documentation `_
* `Project page at Heptapod `_