Add generated README.rst

Needed for installation, e.g.: https://github.com/jedie/python-creole/runs/420788311

3 files changed, 625 insertions, 3 deletions

diff --git a/.gitignore b/.gitignore
index 9d54f44..3ed4524 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,6 +11,3 @@
 /.coverage
 
 .tox
-
-# Will be generated from README.creole and added to sdist
-/README.rst
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..af848fb
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,619 @@
+===================
+about python-creole
+===================
+
+python-creole is a OpenSource (GPL) Python lib for converting markups.
+python-creole is pure python. No external libs needed.
+
+Compatible Python Versions (see `tox.ini <https://github.com/jedie/python-creole/blob/master/tox.ini>`_ or `.travis.yml <https://github.com/jedie/python-creole/blob/master/.travis.yml>`_):
+
+* 3.8, 3.7, 3.6
+
+* PyPy3
+
+Existing converters:
+
+* creole -> html
+
+* html -> creole markup
+
+* reSt -> html (for clean html code)
+
+* html -> reStructuredText markup (only a subset of reSt supported)
+
+* html -> textile markup (not completed yet)
+
+The creole2html part based on the creole markup parser and emitter from the MoinMoin project by Radomir Dopieralski and Thomas Waldmann.
+
++-----------------------------------+
+| |Build Status on github|          |
++-----------------------------------+
+| |Build Status on travis-ci.org|   |
++-----------------------------------+
+| |Coverage Status on coveralls.io| |
++-----------------------------------+
+| |Status on landscape.io|          |
++-----------------------------------+
+
+.. |Build Status on github| image:: https://github.com/jedie/python-creole/workflows/test/badge.svg?branch=master
+.. |Build Status on travis-ci.org| image:: https://travis-ci.org/jedie/python-creole.svg
+.. _travis-ci.org/jedie/python-creole: https://travis-ci.org/jedie/python-creole/
+.. |Coverage Status on coveralls.io| image:: https://coveralls.io/repos/jedie/python-creole/badge.svg
+.. _coveralls.io/r/jedie/python-creole: https://coveralls.io/r/jedie/python-creole
+.. |Status on landscape.io| image:: https://landscape.io/github/jedie/python-creole/master/landscape.svg
+.. _landscape.io/github/jedie/python-creole/master: https://landscape.io/github/jedie/python-creole/master
+
+=======
+install
+=======
+
+Python packages available on: `http://pypi.python.org/pypi/python-creole/ <http://pypi.python.org/pypi/python-creole/>`_
+
+::
+
+    ~$ pip install python-creole
+
+To setup a virtualenv via Poetry, see ``unittests`` section below.
+
+------------
+dependencies
+------------
+
+For the most parts (``creole2html`` and ``html2creole``) no external libraries are needed.
+
+For all functionality (and running the unittests) these modules are needed:
+
+* `docutils <http://pypi.python.org/pypi/docutils/>`_ (for the ReStructuredText stuff)
+
+* `textile <http://pypi.python.org/pypi/textile/>`_ (for html2textile tests)
+
+=======
+example
+=======
+
+-----------
+creole2html
+-----------
+
+Convert creole markup to html code:
+
+::
+
+    >>> from creole import creole2html
+    >>> creole2html("This is **creole //markup//**")
+    u'<p>This is <strong>creole <i>markup</i></strong></p>\n'
+
+-----------
+html2creole
+-----------
+
+Convert html code back into creole markup:
+
+::
+
+    >>> from creole import html2creole
+    >>> html2creole(u'<p>This is <strong>creole <i>markup</i></strong></p>\n')
+    u'This is **creole //markup//**'
+
+---------
+rest2html
+---------
+
+Convert ReStructuredText into clean html code (needs `docutils`_):
+
+::
+
+    >>> from creole.rest2html.clean_writer import rest2html
+    >>> rest2html(u"A ReSt link to `PyLucid CMS <http://www.pylucid.org>`_ :)")
+    u'<p>A ReSt link to <a href="http://www.pylucid.org">PyLucid CMS</a> :)</p>\\n'
+
+(more information: `rest2html wiki page <https://github.com/jedie/python-creole/wiki/rest2html>`_)
+
+---------
+html2rest
+---------
+
+Convert html code into ReStructuredText markup:
+
+::
+
+    >>> from creole import html2rest
+    >>> html2rest(u'<p>This is <strong>ReStructuredText</strong> <em>markup</em>!</p>')
+    u'This is **ReStructuredText** *markup*!'
+
+------------
+html2textile
+------------
+
+Convert html code into textile markup
+
+::
+
+    >>> from creole import html2textile
+    >>> html2textile(u'<p>This is <strong>textile <i>markup</i></strong>!</p>')
+    u'This is *textile __markup__*!'
+
+See also: `http://github.com/jedie/python-creole/blob/master/demo.py <http://github.com/jedie/python-creole/blob/master/demo.py>`_
+
+=====================
+Image size additional
+=====================
+
+You can pass image width/height in image tags, e.g.:
+
+::
+
+    >>> from creole import creole2html
+    >>> creole_markup="""{{foobar.jpg|image title|90x160}}"""
+    >>> creole2html(creole_markup)
+    '<p><img src="foobar.jpg" title="image title" alt="image title" width="90" height="160" /></p>'
+
+The third part (``90x160``) is not in creole standard, you can force a *strict* mode, e.g.:
+
+::
+
+    >>> creole2html(creole_markup, strict=True)
+    '<p><img src="foobar.jpg" title="image title|90x160" alt="image title|90x160" /></p>'
+
+================================
+Source code highlighting support
+================================
+
+You can find a example macro which highlight source code thanks to the pygments
+library. It is located here: `/creole/shared/example_macros.py <https://github.com/jedie/python-creole/blob/master/creole/shared/example_macros.py>`_.
+Here is how to use it:
+
+::
+
+    >>> from creole import creole2html
+    >>> from creole.shared.example_macros import code
+    >>> creole_markup="""<<code ext=".py">>#some code\nprint('coucou')\n<</code>>"""
+    >>> creole2html(creole_markup, macros={'code': code})
+
+=====================
+commandline interface
+=====================
+
+If you have python-creole installed, you will get these simple CLI scripts:
+
+* creole2html
+
+* html2creole
+
+* html2rest
+
+* html2textile
+
+Here the ``--help`` output from ``html2creole``:
+
+::
+
+    $ html2creole --help
+    usage: html2creole [-h] [-v] [--encoding ENCODING] sourcefile destination
+    
+    python-creole is an open-source (GPL) markup converter in pure Python for:
+    creole2html, html2creole, html2ReSt, html2textile
+    
+    positional arguments:
+      sourcefile           source file to convert
+      destination          Output filename
+    
+    optional arguments:
+      -h, --help           show this help message and exit
+      -v, --version        show program's version number and exit
+      --encoding ENCODING  Codec for read/write file (default encoding: utf-8)
+
+Example to convert a html file into a creole file:
+
+::
+
+    $ html2creole foobar.html foobar.creole
+
+=============
+documentation
+=============
+
+We store documentation/examples into the project wiki:
+
+* `https://github.com/jedie/python-creole/wiki <https://github.com/jedie/python-creole/wiki>`_
+
+How to handle unknown html tags in html2creole:
+
+* `https://github.com/jedie/python-creole/wiki/Unknown-Html-Tags <https://github.com/jedie/python-creole/wiki/Unknown-Html-Tags>`_
+
+Contributers should take a look at this page:
+
+* `https://github.com/jedie/python-creole/wiki/Developer-Info <https://github.com/jedie/python-creole/wiki/Developer-Info>`_
+
+Creole Markup Cheat Sheet can be found here: `http://www.wikicreole.org/wiki/CheatSheet <http://www.wikicreole.org/wiki/CheatSheet>`_
+
+|Creole Markup Cheat Sheet|
+
+.. |Creole Markup Cheat Sheet| image:: http://www.wikicreole.org/imageServlet?page=CheatSheet%2Fcreole_cheat_sheet.png&width=340
+
+---------
+unittests
+---------
+
+::
+
+    # clone repository (or use your fork):
+    ~$ git clone https://github.com/jedie/python-creole.git
+    ~$ cd python-creole
+    
+    # install or update poetry:
+    ~/python-crole$ make install-poetry
+    
+    # install python-creole via poetry:
+    ~/python-crole$ make install
+    
+    # Run pytest:
+    ~/python-crole$ make pytest
+    
+    # Run pytest via tox with all environments:
+    ~/python-crole$ make tox
+    
+    # Run pytest via tox with one Python version:
+    ~/python-crole$ make tox-py38
+    ~/python-crole$ make tox-py37
+    ~/python-crole$ make tox-py36
+
+--------------------
+Use creole in README
+--------------------
+
+With python-creole you can convert a README on-the-fly from creole into ReStructuredText in setup.py
+How to do this, read: `https://github.com/jedie/python-creole/wiki/Use-In-Setup <https://github.com/jedie/python-creole/wiki/Use-In-Setup>`_
+
+Note: In this case you must install **docutils**! See above.
+
+=======
+history
+=======
+
+* *dev* - `compare v1.4.1...master <https://github.com/jedie/python-creole/compare/v1.4.1...master>`_ 
+
+    * TBC
+
+* v1.4.1 - 2020-01-19 - `compare v1.4.0...master <https://github.com/jedie/python-creole/compare/v1.4.0...master>`_ 
+
+    * Remove Python v2 support code
+
+    * `Fix "Undefined substitution referenced" error <https://github.com/jedie/python-creole/issues/26>`_ contributed by dforsi
+
+    * `Fix regression in tests for setup_utils <https://github.com/jedie/python-creole/pull/37>`_ contributed by jugmac00
+
+    * Fix code style with: autopep8
+
+    * sort imports with isort
+
+    * change old ``%-formatted`` and ``.format(...)`` strings into Python 3.6+'s ``f-strings`` with flynt
+
+    * Activate linting in CI pipeline
+
+* v1.4.0 - 2020-01-19 - `compare v1.3.2...master <https://github.com/jedie/python-creole/compare/v1.3.2...master>`_ 
+
+    * modernize project:
+
+        * use poetry
+
+        * Add a ``Makefile``
+
+        * use pytest and tox
+
+        * remove Python v2 support
+
+        * Test with Python v3.6, v3.7 and v3.8
+
+* v1.3.2 - 2018-02-27 - `compare v1.3.1...v1.3.2 <https://github.com/jedie/python-creole/compare/v1.3.1...v1.3.2>`_ 
+
+    * Adding optional img size to creole2html and html2creole contributed by `John Dupuy <https://github.com/JohnAD>`_
+
+    * run tests also with python 3.5 and 3.6
+
+* v1.3.1 - 2015-08-15 - `compare v1.3.0...v1.3.1 <https://github.com/jedie/python-creole/compare/v1.3.0...v1.3.1>`_ 
+
+    * Bugfix for "Failed building wheel for python-creole"
+
+* v1.3.0 - 2015-06-02 - `compare v1.2.2...v1.3.0 <https://github.com/jedie/python-creole/compare/v1.2.2...v1.3.0>`_ 
+
+    * Refactory internal file structure
+
+    * run unittests and doctests with nose
+
+    * Refactor CLI tests
+
+    * skip official support for Python 2.6
+
+    * small code cleanups and fixes.
+
+    * use **json.dumps()** instead of **repr()** in some cases
+
+* v1.2.2 - 2015-04-05 - `compare v1.2.1...v1.2.2 <https://github.com/jedie/python-creole/compare/v1.2.1...v1.2.2>`_ 
+
+    * Bugfix textile unittests if url scheme is unknown
+
+    * migrate google-code Wiki to github and remove google-code links
+
+* v1.2.1 - 2014-09-14 - `compare v1.2.0...v1.2.1 <https://github.com/jedie/python-creole/compare/v1.2.0...v1.2.1>`_ 
+
+    * Use origin PyPi code to check generated reStructuredText in setup.py
+
+    * Update unitest for textile v2.1.8
+
+* v1.2.0 - 2014-05-15 - `compare v1.1.1...v1.2.0 <https://github.com/jedie/python-creole/compare/v1.1.1...v1.2.0>`_ 
+
+    * NEW: Add ``<<code>>`` example macro (Source code highlighting with pygments) - implemented by Julien Enselme
+
+    * NEW: Add ``<<toc>>`` macro to create a table of contents list
+
+    * Bugfix for: AttributeError: 'CreoleParser' object has no attribute '_escaped_char_repl'
+
+    * Bugfix for: AttributeError: 'CreoleParser' object has no attribute '_escaped_url_repl'
+
+    * API Change: Callable macros will raise a TypeError instead of create a DeprecationWarning (Was removed in v0.5)
+
+* v1.1.1 - 2013-11-08
+
+    * Bugfix: Setup script exited with error: can't copy 'README.creole': doesn't exist or not a regular file
+
+* v1.1.0 - 2013-10-28
+
+    * NEW: Simple commandline interface added.
+
+* v1.0.7 - 2013-08-07
+
+    * Bugfix in 'clean reStructuredText html writer' if docutils => v0.11 used.
+
+    * Bugfix for PyPy 2.1 usage
+
+* v1.0.6 - 2012-10-15
+
+    * Security fix in rest2html: Disable "file_insertion_enabled" and "raw_enabled" as default.
+
+* v1.0.5 - 2012-09-03
+
+    * made automatic protocol links more strict: Only whitespace before and at the end are allowed.
+
+    * Bugfix: Don't allow ``ftp:/broken`` (Only one slash) to be a link.
+
+* v1.0.4 - 2012-06-11
+
+    * html2rest: Handle double link/image substitution and raise better error messages
+
+    * Bugfix in unittests (include test README file in python package).  Thanks to Wen Heping for reporting this.
+
+* v1.0.3 - 2012-06-11
+
+    * Bugfix: ``AttributeError: 'module' object has no attribute 'interesting_cdata'`` from HTMLParser patch. Thanks to Wen Heping for reporting this.
+
+    * Fix a bug in get_long_description() ReSt test for Py3k and his unittests.
+
+    * Use Travis CI, too.
+
+* v1.0.2 - 2012-04-04
+
+    * Fix "`AttributeError: 'NoneType' object has no attribute 'parent' <https://github.com/jedie/python-creole/issues/6>`_" in html2creole.
+
+* v1.0.1 - 2011-11-16
+
+    * Fix "`TypeError: expected string or buffer <https://github.com/jedie/python-creole/issues/5>`_" in rest2html.
+
+    * `Bugfix in exception handling. <https://github.com/jedie/python-creole/commit/e8422f944709a5f8c2c6a8c8a58a84a92620f035>`_
+
+* v1.0.0 - 2011-10-20
+
+    * Change API: Replace 'parser_kwargs' and 'emitter_kwargs' with separate arguments. (More information on `API Wiki Page <https://github.com/jedie/python-creole/wiki/API>`_)
+
+* v0.9.2
+
+    * Turn zip_safe in setup.py on and change unittests API.
+
+* v0.9.1
+
+    * Many Bugfixes, tested with CPython 2.6, 2.7, 3.2 and PyPy v1.6
+
+* v0.9.0
+
+    * Add Python v3 support (like `http://python3porting.com/noconv.html <http://python3porting.com/noconv.html>`_ strategy)
+
+    * move unittests into creole/tests/
+
+    * Tested with Python 2.7.1, 3.2 and PyPy v1.6.1 15798ab8cf48 jit
+
+* v0.8.5
+
+    * Bugfix in html2creole: ignore links without href
+
+* v0.8.4
+
+    * Bugfix in html parser if list tag has attributes: `https://code.google.com/p/python-creole/issues/detail?id=19#c4 <https://code.google.com/p/python-creole/issues/detail?id=19#c4>`_
+
+* v0.8.3
+
+    * Better error message if given string is not unicode: `https://code.google.com/p/python-creole/issues/detail?id=19 <https://code.google.com/p/python-creole/issues/detail?id=19>`_
+
+* v0.8.2
+
+    * Bugfix in get_long_description() error handling (*local variable 'long_description_origin' referenced before assignment*)
+
+* v0.8.1
+
+    * Bugfix for installation under python 2.5
+
+    * Note: `setup helper <https://github.com/jedie/python-creole/wiki/Use-In-Setup>`_ changed: rename ``GetLongDescription(...)`` to ``get_long_description(...)``
+
+* v0.8
+
+    * New GetLongDescription() helper for setup.py, see: `https://github.com/jedie/python-creole/wiki/Use-In-Setup`_
+
+* v0.7.3
+
+    * Bugfix in html2rest:
+
+        * table without ``<th>`` header
+
+        * new line after table
+
+        * create reference hyperlinks in table cells intead of embedded urls.
+
+        * Don't always use raise_unknown_node()
+
+    * Add child content to raise_unknown_node()
+
+* v0.7.2
+
+    * Activate ``----`` to ``<hr>`` in html2rest
+
+    * Update demo.py
+
+* v0.7.1
+
+    * Bugfix if docutils are not installed
+
+    * API change: rest2html is now here: ``from creole.rest2html.clean_writer import rest2html`` 
+
+* v0.7.0
+
+    * **NEW**: Add a html2reStructuredText converter (only a subset of reSt supported)
+
+* v0.6.1
+
+    * Bugfix: separate lines with one space in "wiki style line breaks" mode
+
+* v0.6
+
+    * **NEW**: html2textile converter
+
+    * some **API changed**!
+
+* v0.5
+
+    * **API changed**:
+
+        * Html2CreoleEmitter optional argument 'unknown_emit' takes now a callable for handle unknown html tags.
+
+        * No macros used as default in creole2html converting.
+
+        * We remove the support for callable macros. Only dict and modules are allowed.
+
+    * remove unknown html tags is default behaviour in html2creole converting.
+
+    * restructure and cleanup sourcecode files.
+
+* v0.4
+
+    * only emit children of empty tags like div and span (contributed by Eric O'Connell)
+
+    * remove inter wiki links and doesn't check the protocol
+
+* v0.3.3
+
+    * Use <tt> when {{{ ... }}} is inline and not <pre>, see: `PyLucid Forum Thread <http://forum.pylucid.org/viewtopic.php?f=3&t=320>`_
+
+    * Bugfix in html2creole: insert newline before new list. TODO: apply to all block tags: `issues 16 <http://code.google.com/p/python-creole/issues/detail?id=16#c5>`_
+
+* v0.3.2
+
+    * Bugfix for spaces after Headline: `issues 15 <https://code.google.com/p/python-creole/issues/detail?id=15>`_
+
+* v0.3.1
+
+    * Make argument 'block_rules' in Parser() optional
+
+* v0.3.0
+
+    * creole2html() has the optional parameter 'blog_line_breaks' to switch from default blog to wiki line breaks
+
+* v0.2.8
+
+    * bugfix in setup.py
+
+* v0.2.7
+
+    * handle obsolete non-closed <br> tag
+
+* v0.2.6
+
+    * bugfix in setup.py
+
+    * Cleanup DocStrings
+
+    * add unittests
+
+* v0.2.5
+
+    * creole2html: Bugfix if "--", "//" etc. stands alone, see also: `issues 12 <http://code.google.com/p/python-creole/issues/detail?id=12>`_
+
+    * Note: bold, italic etc. can't cross line any more.
+
+* v0.2.4
+
+    * creole2html: ignore file extensions in image tag
+
+        * see also: `issues 7 <http://code.google.com/p/python-creole/issues/detail?id=7>`_
+
+* v0.2.3
+
+    * html2creole bugfix/enhanced: convert image tag without alt attribute:
+
+        * see also: `issues 6 <http://code.google.com/p/python-creole/issues/detail?id=6>`_
+
+        * Thanks Betz Stefan alias 'encbladexp'
+
+* v0.2.2
+
+    * html2creole bugfix: convert ``<a href="/url/">Search & Destroy</a>``
+
+* v0.2.1
+
+    * html2creole bugfixes in:
+
+        * converting tables: ignore tbody tag and better handling p and a tags in td
+
+        * converting named entity
+
+* v0.2
+
+    * remove all django template tag stuff: `issues 3 <http://code.google.com/p/python-creole/issues/detail?id=3>`_
+
+    * html code always escaped
+
+* v0.1.1
+
+    * improve macros stuff, patch by Vitja Makarov: `issues 2 <http://code.google.com/p/python-creole/issues/detail?id=2>`_
+
+* v0.1.0
+
+    * first version cut out from `PyLucid CMS <http://www.pylucid.org>`_
+
+first source code was written 27.11.2008: `Forum thread (de) <http://www.python-forum.de/viewtopic.php?f=3&t=16742>`_
+
+-------------
+Project links
+-------------
+
++--------+------------------------------------------------+
+| GitHub | `https://github.com/jedie/python-creole`_      |
++--------+------------------------------------------------+
+| Wiki   | `https://github.com/jedie/python-creole/wiki`_ |
++--------+------------------------------------------------+
+| PyPi   | `https://pypi.org/project/python-creole/`_     |
++--------+------------------------------------------------+
+
+.. _https://github.com/jedie/python-creole: https://github.com/jedie/python-creole
+.. _https://pypi.org/project/python-creole/: https://pypi.org/project/python-creole/
+
+--------
+donation
+--------
+
+* `paypal.me/JensDiemer <https://www.paypal.me/JensDiemer>`_
+
+* `Flattr This! <https://flattr.com/submit/auto?uid=jedie&url=https%3A%2F%2Fgithub.com%2Fjedie%2Fpython-creole%2F>`_
+
+* Send `Bitcoins <http://www.bitcoin.org/>`_ to `1823RZ5Md1Q2X5aSXRC5LRPcYdveCiVX6F <https://blockexplorer.com/address/1823RZ5Md1Q2X5aSXRC5LRPcYdveCiVX6F>`_
+
+------------
+
+``Note: this file is generated from README.creole with "python-creole" at 2020-02-01 12:50:27``
\ No newline at end of file
diff --git a/creole/setup_utils.py b/creole/setup_utils.py
index c45e194..24b1b1a 100644
--- a/creole/setup_utils.py
+++ b/creole/setup_utils.py
@@ -41,6 +41,7 @@
 """
 
 import codecs
+import datetime
 import os
 import shutil
 import subprocess
@@ -159,6 +160,11 @@ def update_rst_readme(package_root, filename='README.creole'):
 
     with rest_readme_path.open('w') as f:
         f.write(rest_readme)
+        f.write('\n\n------------\n\n')
+        dt = datetime.datetime.utcnow()
+        dt = dt.replace(microsecond=0)
+        dt = dt.isoformat(sep=' ')
+        f.write(f'``Note: this file is generated from {filename} with "python-creole" at {dt}``')
 
     print('done.')