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 -- 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 [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/leo-editor/f19809b7-a8ee-4c05-94f1-f31f0ba9e7e6%40googlegroups.com.
