README file

The Python Package Index can display the project's README file or the value of long_description on the package page in the PyPI portal. PyPI is able to interpret the markup used in the long_description content and render it as HTML on the package page. The type of markup language is controlled through the long_description_content_type argument of the setup() call. For now, there are the following three choices for markup available:

• Plain text with long_description_content_type='text/plain'
• reStructuredText with long_description_content_type='text/x-rst'
• Markdown with long_description_content_type='text/markdown'

Markdown and reStructuredText are the most popular choices among Python developers, but some might still want to use different markup languages for various reasons. If you want to use something different as your markup language for your project's README, you can still provide it as a project description on the PyPI page in a readable form. The trick lies in using the pypandoc package to translate your other markup language into reStructuredText (or Markdown) while uploading the package to the Python Package Index. It is important to do it with a fallback to plain content of your README file, so the installation won't fail if the user has no pypandoc installed. The following is an example of a setup.py script that is able to read the content of the README file written in AsciiDoc markup language and translate it to reStructuredText before including a long_description argument: 

from setuptools import setup
try:
    from pypandoc import convert

    def read_md(file_path):
        return convert(file_path, to='rst', format='asciidoc')

except ImportError:
    convert = None
    print(
        "warning: pypandoc module not found, "
        "could not convert Asciidoc to RST"
    )

    def read_md(file_path):
         with open(file_path, 'r') as f:
            return f.read()

README = os.path.join(os.path.dirname(__file__), 'README')

setup(
    name='some-package',
    long_description=read_md(README),
    long_description_content_type='text/x-rst',
    # ...
)