Problems getting Python 3 docutils.conf to work


#1

I have a two-parts question / problem about the docutils.conf file referred to in the Python 3 docutils documentation:

http://docutils.sourceforge.net/docs/user/config.html#configuration-files

  • Why does that documentation refer to docutils.conf but installing docutils doesn’t include it in the installation?

  • If one acquires a copy of docutils.conf,how can one put that file to work?

A supplementary question is where, if at all, can one find some truly useful documentation about docutils, including but not limited to examples of docutils.conf? I’ve read LOTS of stuff, none of which seems especially coherent or informative.

BACKGROUND

I’m running docutils on a Windows 7 64-bit system with Python 3.5.2 and the BASH command line that accompanies Git for Windows.

In pursuit of figuring out my docutils.conf problem,I used two methods to install Python 3 docutils, both of which seemed to provide working instances:

  1. I initially used pip to install docutils 0.13, the version pip considers to be most current as of today.

  2. I then used pip to uninstall that version and used the command line python setup.py install to install version 0.14rc1 from a tar.gz package downloaded via:

    https://sourceforge.net/projects/docutils/

I could use either version of docutils to run rst2html.py and produce html output. So it seemed that docutils was / is correctly installed.

##But where is docutils.conf?
By default, rst2html.py (and its siblings) embeds CSS in the HTML output files. I didn’t want that so I ran the command

rst2html.py --link-stylesheet input.rst outputfolder/output.html

That produced the desired result: the HTML output now referenced the CSS files in the html outputs folder.

But threading multiple such options onto a single command line quickly became unwieldy. So per the documentation cited above, I thought I’d try to make use of docutils.conf.

HOWEVER, no instance of docutils.conf was installed along with docutils. In fact I had NO instance of docutils.conf anywhere on my computer (except in the tar.gz installation package I used to install version 0.14rc1 as described above).

SO that’s my first question: Why is docutils.conf cited in the documentation, AND present in the installation package I downloaded, BUT not incorporated into the installation – as the documentation seems to indicate it should be?

How to get docutils.conf working?

The installation package included /tools/docutils.conf that matched the default instance of that file described in the documentation. (Subdirectories in the tar.gz installation package contained their own, apparently specialized instances of docutils.conf that I’m ignoring for the time being.) So I:

  1. Copied docutils-0.14rc1/tools/docutils.conf into my project directory.

  2. Observed that by default the [html4css1 writer] section of that file contained embed-stylesheet: no.
    (Which was exactly what I wanted.)

  3. Per the documentation, revised the default stylesheet-path value to reference the CSS stylesheets
    html4css1.css and my-docutils.css I placed in my HTML output directory.

  4. In the BASH for Windows shell, ran a BASH script that contained the command:
    rst2html.py --config=./docutils.conf input.rst outputfolder/output.html.

The command produced HTML output BUT the resulting HTML output contained inline CSS rather than referencing it.

  • I’ve tried different variations of commands and settings. I just can’t get rst2html.py (or any of its similar docutils siblings) to recognize docutils.conf or take settings from it.

  • I’ve also done LOTS of Web searches for information about docutils.conf. Whatever “documentation” for docutils I found provides very little help for docutils.conf.

In summary…

Can anyone please help me get the pieces working together?

Also, has anyone found some genuinely informative documentation about docutils.conf?
(http://docutils.sourceforge.net/docs/user/config.html doesn’t provide informative examples.)

Is the expectation that one read the Python 3 code to figure out how to set it up? Or?

Cheers & thanks,
Riley
SFO