Discuss: what should Leo's sphinx commands do?

[Edward K. Ream]

I am working on the sphinx and sphinx-with-preview commands.  These commands convert one or more @sphinx trees into sphinx input files. The commands then call the sphinx-build tool to create one or more sphinx output files.

These two sphinx commands are similar to the corresponding adoc and pandoc commands.  However, the sphinx-build tool works differently from the asciidoctor or pandoc tools, and this raises questions about what the sphinx commands should do. I'd like your comments and suggestions.

Building the input files

This is a straightforward process. The code (in markup.write_root & helpers) is common to the adoc, pandoc and sphinx commands.  It traverses the @adoc, @pandoc or @sphinx tree, converting headlines to the appropriate markup for sections.  I have no questions regarding this process.

Sphinx-build

sphinx-build is different from asciidoctor and pandoc in several ways.

1. Options:  sphinx-build --help starts with:

   usage: sphinx-build [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]

In particular, the SOURCEDIR and OUTPUTDIR directories must be different. See below.

2. Typically, sphinx users create a conf.py file that specifies various options.  The sphinx-quickstart tool does that automatically. The sphinx-quickstart tool also creates _build and _static directories for output.

So given an input file x, the sphinx commands can't simply specify x.html as the output file. The output file would typically be written to _build/html.

Questions

Here are the questions I have:

1. Should invoking the sphinx-build tool be optional?

Not invoking sphinx-build is the most flexible option. The user could then (via @command) invoke sphinx-build as they like, and display results in the browser if desired.

2. What command should Leo use to invoke sphinx-build?

Invoking 'make html' would seem to be a reasonable default, when conf.py is present.

3. How should the user specify that command, and what should the defaults be?

I am willing to add various settings if you all want that flexibility.

Summary

I'd like your comments to the questions given above.

Sphinx is sufficiently different from asciidoctor and pandoc that new Leo settings seem to be required.

Please correct me if I have misstated or omitted anything regarding typical sphinx usage.

It will be straightforward to do anything you might want.  I plan to complete all the sphinx-related work before releasing Leo 6.1b1.

Edward

[Chris George]

When I use sphinx, step one is to always create a directory for the project. I then run sphinx-quickstart to create the conf.py and the _build and _static directories.

The ideal for my workflow would be to start with an @sphinx node that would do all that for me. ie. in the headline @sphinx ~/sphinx/my_new_project and save the Leo file would create the directory my_new_project, run sphinx-quickstart, create a child node @clean ~/sphinx/my_new_project/conf.py, and an initial index.rst, also as a child node.

All of that is just housekeeping that can easily be done via a variety of methods.

The main thing, for me, is the ability to view the rendered sphinx document (html) in the viewrendered pane, live, in real time, while editing a node under the @sphinx tree.

As far as rendering the entire sphinx project as html to view in a browser, that too can be achieved in a number of ways. The workflow above would have a copy of both the input and output files updated in real time so viewing the entire project in the viewrendered pane (when the top level @sphinx node is selected) should be pretty straight forward.

The sphinx-autobuild command might be useful for this as it starts a basic http server and auto-updates itself when the content of the input files changes.

One of Leo's great strengths is flexibility, settings, and reasonable defaults. Automating the basic housekeeping tasks would work for me, but other people might have different ideas, so settings are a good thing.

HTH,

Chris

--
You received this message because you are subscribed to the Google Groups "leo-editor" group.
To unsubscribe from this group and stop receiving emails from it, send an email to leo-editor+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/leo-editor/f19809b7-a8ee-4c05-94f1-f31f0ba9e7e6%40googlegroups.com.

[Edward K. Ream]

On Fri, Oct 18, 2019 at 9:05 AM Chris George <techn...@gmail.com> wrote:

When I use sphinx, step one is to always create a directory for the project. I then run sphinx-quickstart to create the conf.py and the _build and _static directories.

Recent revs in "devel" support that work flow, I think.  The new code is experimental.

There are now four new settings, used by the markup.run_sphinx method. They are in leoSettings.leo, in the node: @settings-->Command options-->sphinx settings:

@string sphinx-command-directory = None

If given, the sphinx command will cd to this directory.
Otherwise, the sphinx command will cd to the directory containing the input file.

@string sphinx-default-command = make html

If given, only this command will be executed after the cd command.

@string sphinx-input-directory = None

Used only if the default command is not given. The input_dir directory specified in the command:
    sphinx-build {input_dir} {output_dir} {i_path}

@string sphinx-output-directory = None

Used only if the default command is not given.
The output_dir directory specified in the command:
    sphinx-build {input_dir} {output_dir} {i_path}

 

The ideal for my workflow would be to start with an @sphinx node that would do all that for me.

I'm not ready to do that yet.

Limitations

At present, the sphinx command always writes rST format headlines.  Perhaps it should look at @language directives.

Due to problems computing the output directive, the sphinx-preview command does nothing. A workaround would be to execute this script:

g.execute_shell_commands({path_to_output_file})

Summary

The new code gives allows some flexibility, but not as much as one might want.

The new code is experimental.  Feel free to suggest changes, or to make them yourself.

Edward