How To Run Sphinx Without Making a Config File

[tbp1...@gmail.com]

Sphinx can turn a ReStructured Text file or series of files into good looking HTML documentation.  But when you read how to get it going, it seems complicated.  You are told the set up a folder and run make to produce a configuration file, which you will probably tinker with.  It's confusing what all the options and settings mean.

Turns out you don't have to do all that if you are willing to live with a basic configuration, but it's probably one you would use most of the time anyway.  Instead of generating a config file, you can just write a small script that passes the most important options to Sphinx directly.  You can write the script in a Leo node and run it with CNTL-B like any other script.

Here is an annotated sample.

import sys

import subprocess

pyexe=sys.executable

cmd=[pyexe,'-m','sphinx','-C',

'-D', 'master_doc=main_doc', # the main RsT file

'-D', 'source_suffix=.rst',  # The RsT file extension 

                             # (set by a Leo setting)

'-D', 'html_theme=bizstyle', # Look on web for other themes

'-D', 'project=my project',  # Project name, can have spaces

'-D', 'copyright=T. B. Passin', # Optional

'.', 'result-dir']           # Directory for generated files

subprocess.call(cmd)

I don't recall just now if Sphinx will make the output directory for you if it doesn't exist.

You can create the file(s) using the rst3 command on an @rst file, or you can just write an RsT file (or file tree) by hand yourself, as an @clean file.  Then run your script and when Sphinx is done it will tell you where to find the output HTML files.  If you use it often, you can make it into a button.

When I need to create a new Sphinx project, I usually copy the script to a new outline and change the key names.

That's it!

[jkn]

Thanks for this - I have been meaning to knock up something to run sphinx standalone for a while now...

[Edward K. Ream]

On Thu, Jul 1, 2021 at 5:21 PM tbp1...@gmail.com <tbp1...@gmail.com> wrote:

Sphinx can turn a ReStructured Text file or series of files into good looking HTML documentation.  But when you read how to get it going, it seems complicated.  You are told the set up a folder and run make to produce a configuration file, which you will probably tinker with.  It's confusing what all the options and settings mean.

LeoDocs.leo contains @edit html\conf.py, which contains the sphinx settings for Leo's web site. conf.py starts with this comment:

# Leo documentation documentation [sic] build configuration file, created by
# sphinx-quickstart on Mon Mar 30 16:39:02 2009.

Imo, using conf.py might be easier in the long run. YMMV.

Edward

[tbp1...@gmail.com]

The annotated line I gave in my first post:

'.', 'result-dir']           # Directory for generated files

actually contains both the source and result directories. In this example, the source is in ".".

[tbp1...@gmail.com]

You have added a bunch of customizations to a standard theme.  My example above works well when you don't need them.  And it's much easier if you want to try out other themes, as I did the other day.  I ran through all the ones that come with Sphinx and a few more I had installed.