path: root/README.creole

= about =

python-creole is a OpenSource (GPL) Python lib for converting markups.
python-creole is pure python. No external libs needed.
It's compatible with Python v2.6-v3.2 and PyPy.

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.


= install =

Python packages available on: [[http://pypi.python.org/pypi/python-creole/]]

{{{
~$ pip install python-creole
}}}

== 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://code.google.com/p/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]]

= 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/exmplate into the project wiki:

* [[http://code.google.com/p/python-creole/w/list]]

How to handle unknown html tags in html2creole:

* [[http://code.google.com/p/python-creole/wiki/UnknownHtmlTags]]

Contributers should take a look at this page:

* [[http://code.google.com/p/python-creole/wiki/DeveloperInfo]]


== unittests ==

[[https://travis-ci.org/jedie/python-creole|python-creole @ Travis CI]]: {{https://secure.travis-ci.org/jedie/python-creole.png?branch=master|Build Status on travis-ci.org}}
* https://travis-ci.org/jedie/python-creole


=== run unittests ===

From source package, use setup.py to run unittests (Works without install python-creole, needs setuptools):
{{{
.../path/to/python-creole$ python setup.py test
}}}

If you have installed python-creole do this to run unittests:
{{{
~$ cd /path/to/site-packages
...path/to/site-packages/$ cd
...path/to/site-packages/python_creole-0.9.0.pre-py2.7.egg$ cd /creole/tests
...path/to/site-packages/python_creole-0.9.0.pre-py2.7.egg/creole/tests$ python all_tests.py
}}}
Note:
* You can pass the arguments {{{--verbose}}} or {{{--quite}}} to **setup.py** and **all_tests.py**
* If you get a error like {{{ImportError: ... No module named creole}}}, then python-creole is not installed successfully, because it's not found in Python {{{sys.path}}}


You can also run tests inside interactive python:
{{{
>>> from creole.tests import run_unittests
>>> run_unittests()
..............................................................................................................................
----------------------------------------------------------------------
Ran 126 tests in 0.966s

>>> from creole.tests.all_tests import run_all_doctests
>>> run_all_doctests()
.....................
----------------------------------------------------------------------
Ran 21 DocTests from 49 files in 0.368s: failed=0, attempted=88
}}}

or do this:
{{{
~$ python -c "from creole.tests import run_unittests;run_unittests()"
..............................................................................................................................
----------------------------------------------------------------------
Ran 126 tests in 0.917s

~$ python -c "from creole.tests.all_tests import run_all_doctests;run_all_doctests()"
.....................
----------------------------------------------------------------------
Ran 21 DocTests from 49 files in 0.368s: failed=0, attempted=88
}}}


== 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://code.google.com/p/python-creole/wiki/UseInSetup

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


= history =

* v1.2.1 - 2014-09-14
** Use origin PyPi code to check generated reStructuredText in setup.py
** Update unitest for textile v2.1.8
* v1.2.0 - 2014-05-15
** 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 [[http://code.google.com/p/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://code.google.com/p/python-creole/wiki/UseInSetup|setup helper]] changed: rename {{{GetLongDescription(...)}}} to {{{get_long_description(...)}}}
* v0.8
** New GetLongDescription() helper for setup.py, see: https://code.google.com/p/python-creole/wiki/UseInSetup
* 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]]


= donation =

* [[http://flattr.com/thing/181554/python-creole|Flattr this!]]
* Send [[http://www.bitcoin.org/|Bitcoins]] to [[https://blockexplorer.com/address/12QK6o7sGw7Dp3Fdfm2qKvyRqzuY2w5da9|12QK6o7sGw7Dp3Fdfm2qKvyRqzuY2w5da9]]


== Project links ==

| Google code   | [[http://code.google.com/p/python-creole/]]
| GitHub        | [[http://github.com/jedie/python-creole]]
| PyPi          | [[http://pypi.python.org/pypi/python-creole/]]
| Shining Panda | [[https://jenkins.shiningpanda.com/python-creole/]]

=== contact ===

Come into the conversation, besides the github communication features:

| Forum   | [[http://www.pylucid.org/en/forum/9/|official python-creole Forum]]
| IRC     | #pylucid on freenode.net (Yes, the PyLucid channel...)
| webchat | http://webchat.freenode.net/?channels=pylucid