Use In Setup

Use Creole for README and create ReSt on-the-fly for setup.py

Introduction

The Package Index used the long_description from setup.py to display a html page.

This long_description must be written in !ReStructuredText, but !ReSt is not very easy to use.

With python-creole you can write your README in creole and convert it on-the-fly in setup.py into !ReStructuredText for the PyPi ;)

Example

Our README.creole on github:

• the raw README.creole
• rendered README.creole

The rendered !ReStructuredText on PyPi:

• http://pypi.python.org/pypi/python-creole/

HowTo

Create a README.creole in your project root (use .creole file extension, so it would be rendered on github as html!)

setup.py

Put this code into your setup.py:

#!/usr/bin/env python
# coding: utf-8

"""
    distutils setup example
    ~~~~~~~~~~~~~~~~~~~~~~~
"""

import os
import sys
from setuptools import setup, find_packages


PACKAGE_ROOT = os.path.dirname(os.path.abspath(__file__))

#_____________________________________________________________________________
# convert creole to ReSt on-the-fly, see also:
# https://github.com/jedie/python-creole/wiki/Use-In-Setup
long_description = None
for arg in ("test", "check", "register", "sdist", "--long-description"):
    if arg in sys.argv:
        try:
            from creole.setup_utils import get_long_description
        except ImportError as err:
            raise ImportError("%s - Please install python-creole - e.g.: pip install python-creole" % err)
        else:
            long_description = get_long_description(PACKAGE_ROOT)
        break
#----------------------------------------------------------------------------


setup(
    ...
    long_description = long_description,
    ...
)

Note: You must install docutils for full functionality, see dependencies section in README.

Note2: You should have a MANIFEST.in file to include README.creole

e.g.:

include AUTHORS LICENSE MANIFEST.in README.creole
recursive-exclude ** **.py[co]

It's a good idea to run a test, before upload to PyPi, e.g.:

$ python setup.py check --restructuredtext
Generating creole to ReSt to html, ok.
running check