docs: How to render a README file?

[guettli]

Please tell us how to use the readme renderer.

I don't understand the current docs I see at https://github.com/pypa/readme_renderer

How can I render a README which is called foo.rst? Is there no command line tool which I can call like this readme_render foo.rst?

[di]

This library is designed to render the descriptions of packages on http://pypi.org. It also allows folks to check whether their RST description will be rendered correctly, which is what the command you're seeing in the docs is for.

If you really wanted to use this library to render a rST file, you could write a short script like:

import sys
from readme_renderer import rst

print(rst.render(open(sys.argv[1]).read()))

And use it like:

$ python render.py foo.rst

which will output HTML.

However, depending on what you're hoping to use this for, you might not want to do that. This library is pretty restrictive about what it will render and does a lot of sanitization of the result (again, since it's designed to be used on pypi.org).

Instead, you may want to use one of the following:

• Docutils
• Sphinx

[guettli]

I want to check my README.rst before I commit.

That's why I would like to use this library, since I want to check the restrictions.

In particular it is about this README: https://github.com/guettli/programming-guidelines/blob/master/README.rst

[di]

I'm a little confused, that repo doesn't look like a Python package, why do you want to make sure the README would render on PyPI?

[guettli]

You see the current state. It will be a python package in the future. But this is a different topic. Thank you for your feedback.

[guettli]

You see the current state. It will be a python package in the future. But this is a different topic. Thank you for your feedback.

[guettli]

You see the current state. It will be a python package in the future. But this is a different topic. Thank you for your feedback.

[di]

In that case, once it has a setup.py file, the command in the README for this project (python setup.py check -r -s) would do the same.

[remram44]

I would also like if there was a way to inspect the output, rather than just a pass/fail status from check. How about a command-line tool, or __main__ module (python -m readme_renderer) to write the HTML output?

[edit: filed #123]