path: root/README.creole

= 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 [[https://github.com/jedie/python-creole/blob/master/tox.ini|tox.ini]] or [[https://github.com/jedie/python-creole/blob/master/.travis.yml|.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.

| {{https://github.com/jedie/python-creole/workflows/test/badge.svg?branch=master|Build Status on github}} ||
| {{https://travis-ci.org/jedie/python-creole.svg|Build Status on travis-ci.org}} | [[https://travis-ci.org/jedie/python-creole/|travis-ci.org/jedie/python-creole]] |
| {{https://coveralls.io/repos/jedie/python-creole/badge.svg|Coverage Status on coveralls.io}} | [[https://coveralls.io/r/jedie/python-creole|coveralls.io/r/jedie/python-creole]] |
| {{https://landscape.io/github/jedie/python-creole/master/landscape.svg|Status on landscape.io}} | [[https://landscape.io/github/jedie/python-creole/master|landscape.io/github/jedie/python-creole/master]] |
| {{https://badge.fury.io/py/python-creole.svg|PyPi version}} | [[https://pypi.org/project/python-creole/|pypi.org/project/python-creole/]] |


= install =

Python packages available on: [[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:

* [[http://pypi.python.org/pypi/docutils/|docutils]] (for the ReStructuredText stuff)
* [[http://pypi.python.org/pypi/textile/|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 [[http://pypi.python.org/pypi/docutils/|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: [[https://github.com/jedie/python-creole/wiki/rest2html|rest2html wiki page]])


== 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]]

= 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: [[https://github.com/jedie/python-creole/blob/master/creole/shared/example_macros.py|/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]]

How to handle unknown html tags in html2creole:

* [[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]]

Creole Markup Cheat Sheet can be found here: http://www.wikicreole.org/wiki/CheatSheet

{{http://www.wikicreole.org/imageServlet?page=CheatSheet%2Fcreole_cheat_sheet.png&width=340|Creole Markup Cheat Sheet}}

== unittests ==

{{{
# clone repository (or use your fork):
~$ git clone https://github.com/jedie/python-creole.git
~$ cd python-creole

# install or update poetry:
~/python-creole$ make install-poetry

# install python-creole via poetry:
~/python-creole$ make install

# Run pytest:
~/python-creole$ make pytest

# Run pytest via tox with all environments:
~/python-creole$ make tox

# Run pytest via tox with one Python version:
~/python-creole$ make tox-py38
~/python-creole$ make tox-py37
~/python-creole$ make tox-py36
}}}

== make targets ==

To see all make targets, just call {{{make}}}:
{{{
~/python-creole$ make
help                 List all commands
install-poetry       install or update poetry
install              install python-creole via poetry
lint                 Run code formatters and linter
fix-code-style       Fix code formatting
tox-listenvs         List all tox test environments
tox                  Run pytest via tox with all environments
tox-py36             Run pytest via tox with *python v3.6*
tox-py37             Run pytest via tox with *python v3.7*
tox-py38             Run pytest via tox with *python v3.8*
pytest               Run pytest
update-rst-readme    update README.rst from README.creole
publish              Release new version to PyPi
}}}

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

Note: In this case you must install **docutils**! See above.


= history =

* *dev* - [[https://github.com/jedie/python-creole/compare/v1.4.2...master|compare v1.4.2...master]]
** TBC
* v1.4.2 - 2020-02-01 - [[https://github.com/jedie/python-creole/compare/v1.4.1...v1.4.2|compare v1.4.1...v1.4.2]]
** Update CI configs on github and travis
** Update {{{Makefile}}}: add {{{make publish}}} and {{{make update-rst-readme}}}
** Add generated {{{README.rst}}} in repository to fix install problems about missing readme
* v1.4.1 - 2020-01-19 - [[https://github.com/jedie/python-creole/compare/v1.4.0...v1.4.1|compare v1.4.0...v1.4.1]]
** Remove Python v2 support code
** [[https://github.com/jedie/python-creole/issues/26|Fix "Undefined substitution referenced" error]] contributed by dforsi
** [[https://github.com/jedie/python-creole/pull/37|Fix regression in tests for setup_utils]] 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 - [[https://github.com/jedie/python-creole/compare/v1.3.2...v1.4.0|compare v1.3.2...v1.4.0]]
** 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 - [[https://github.com/jedie/python-creole/compare/v1.3.1...v1.3.2|compare v1.3.1...v1.3.2]]
** Adding optional img size to creole2html and html2creole contributed by [[https://github.com/JohnAD|John Dupuy]]
** run tests also with python 3.5 and 3.6
* v1.3.1 - 2015-08-15 - [[https://github.com/jedie/python-creole/compare/v1.3.0...v1.3.1|compare v1.3.0...v1.3.1]]
** Bugfix for "Failed building wheel for python-creole"
* v1.3.0 - 2015-06-02 - [[https://github.com/jedie/python-creole/compare/v1.2.2...v1.3.0|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 - [[https://github.com/jedie/python-creole/compare/v1.2.1...v1.2.2|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 - [[https://github.com/jedie/python-creole/compare/v1.2.0...v1.2.1|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 - [[https://github.com/jedie/python-creole/compare/v1.1.1...v1.2.0|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 "[[https://github.com/jedie/python-creole/issues/6|AttributeError: 'NoneType' object has no attribute 'parent']]" in html2creole.
* v1.0.1 - 2011-11-16
** Fix "[[https://github.com/jedie/python-creole/issues/5|TypeError: expected string or buffer]]" in rest2html.
** [[https://github.com/jedie/python-creole/commit/e8422f944709a5f8c2c6a8c8a58a84a92620f035|Bugfix in exception handling.]]
* v1.0.0 - 2011-10-20
** Change API: Replace 'parser_kwargs' and 'emitter_kwargs' with separate arguments. (More information on [[https://github.com/jedie/python-creole/wiki/API|API Wiki Page]])
* 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 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
* v0.8.3
** Better error message if given string is not unicode: 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: [[https://github.com/jedie/python-creole/wiki/Use-In-Setup|setup helper]] 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: [[http://forum.pylucid.org/viewtopic.php?f=3&t=320|PyLucid Forum Thread]]
** Bugfix in html2creole: insert newline before new list. TODO: apply to all block tags: [[http://code.google.com/p/python-creole/issues/detail?id=16#c5|issues 16]]
* v0.3.2
** Bugfix for spaces after Headline: [[https://code.google.com/p/python-creole/issues/detail?id=15|issues 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: [[http://code.google.com/p/python-creole/issues/detail?id=12|issues 12]]
** Note: bold, italic etc. can't cross line any more.
* v0.2.4
** creole2html: ignore file extensions in image tag
*** see also: [[http://code.google.com/p/python-creole/issues/detail?id=7|issues 7]]
* v0.2.3
** html2creole bugfix/enhanced: convert image tag without alt attribute:
*** see also: [[http://code.google.com/p/python-creole/issues/detail?id=6|issues 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: [[http://code.google.com/p/python-creole/issues/detail?id=3|issues 3]]
** html code always escaped
* v0.1.1
** improve macros stuff, patch by Vitja Makarov: [[http://code.google.com/p/python-creole/issues/detail?id=2|issues 2]]
* v0.1.0
** first version cut out from [[http://www.pylucid.org|PyLucid CMS]]

first source code was written 27.11.2008: [[http://www.python-forum.de/viewtopic.php?f=3&t=16742|Forum thread (de)]]


== Project links ==

| GitHub        | [[https://github.com/jedie/python-creole]]
| Wiki          | [[https://github.com/jedie/python-creole/wiki]]
| PyPi          | [[https://pypi.org/project/python-creole/]]


== donation

* [[https://www.paypal.me/JensDiemer|paypal.me/JensDiemer]]
* [[https://flattr.com/submit/auto?uid=jedie&url=https%3A%2F%2Fgithub.com%2Fjedie%2Fpython-creole%2F|Flattr This!]]
* Send [[http://www.bitcoin.org/|Bitcoins]] to [[https://blockexplorer.com/address/1823RZ5Md1Q2X5aSXRC5LRPcYdveCiVX6F|1823RZ5Md1Q2X5aSXRC5LRPcYdveCiVX6F]]