rst2html on full python project

Question

How can I configure rst2html to run on a full Python project instead of a single file?

I'm used to epydoc generating my docs, but thinking to use reStructuredText because it's PyCharm default (I know we as well could change PyCharm to epytext)

Answer 1

rst2html cannot do that by itself. It's a ridiculously thin wrapper over docutils.core.publish_cmdline. Check it's source:

https://github.com/docutils-mirror/docutils/blob/master/tools/rst2html.py

If you want to process several .rst files, you could write a short shell script that calls rst2html on each file.

Alternatively you can write a Python script. Here is an example:

# https://docs.python.org/3/library/pathlib.html
from pathlib import Path

# https://pypi.org/project/docutils/
import docutils.io, docutils.core

def rst2html(source_path):
    # mostly taken from
    # https://github.com/getpelican/pelican/
    pub = docutils.core.Publisher(
        source_class=docutils.io.FileInput,
        destination_class=docutils.io.StringOutput)
    pub.set_components('standalone', 'restructuredtext', 'html')
    pub.process_programmatic_settings(None, None, None)
    pub.set_source(source_path=str(source_path))
    pub.publish()

    html = pub.writer.parts['whole']

    return html

SRC_DIR = Path('.')
DST_DIR = Path('.')

for rst_file in SRC_DIR.iterdir():
    if rst_file.is_file() and rst_file.suffix == '.rst':

        html = rst2html(rst_file)

        with open(DST_DIR / (rst_file.stem + '.html'), 'w') as f:
            f.write(html)

A useful reference could be:

http://docutils.sourceforge.net/docs/api/publisher.html