I hit the publish button too soon, sorry! Here's my directory structure
again:
gf4-docs.leo
docs
sphinx
images
My source rst files live in the *sphinx* directory and they can reference
graphics in the *images* directory. The generated HTML files are in the
*docs* directory.
The node with the script that runs the above code is also in the same
outline, at the same level and above the entire document tree. It's
headline reads @button Build HTML . You could have another similar script
to create a pdf file - if rst2pdf is working right these days, anyway - and
you can have one button for each script.
I've developed this way of generating Sphinx documentation over many years
and iterations and it's the one I like best so far. Give it try and see
it it works for you!
On Sunday, March 3, 2024 at 4:23:36 PM UTC-5 Thomas Passin wrote:
> I don't know about a "gentle" introduction, but VR3 has an extensive
> docstring you can read by means of the Plugins menu.
>
> I use Sphinx a lot, and normally I don't even create a Sphinx
> configuration file. I find I can do enough configuration for my needs with
> command-line parameters, which I supply with a little script that I can
> attach to a button. The script would be specialized for a particular
> outline so the button won't show up for all outlines.
>
> Here is one of the scripts I use. It seems more complicated than it is,
> but it lets you start from any node in the outline so you don't have to
> remember to navigate to the top of the @rst tree.
>
> @language python
> from sys import executable
> import subprocess
> import os
>
> target = None
> HEAD = "GF4 User's Guide"
> p0 = c.p
> for p in c.all_unique_positions():
> if p.h.startswith(HEAD):
> target = p
> c.selectPosition(target)
> break
> if target:
> c.k.simulateCommand('rst3')
>
> # Thw rst3 command writes to correct (@path sphinx) directory
> # but Sphinx will look in current directory, which may
> # not be the same. So -
> # if we start from a selected node outside the
> # @path sphinx tree, temporarily cd to the docs directory.
> cwd = os.getcwd()
> if not cwd.endswith('sphinx'):
> temp_cwd = os.path.join(cwd, 'sphinx')
> os.chdir(temp_cwd)
>
> # Other likely themes:
> #'-D', 'html_theme=sphinx_book_theme',
> #'-D', 'html_theme=bizstyle',
>
> cmd = [executable, '-m', 'sphinx', '-C',
> '-b', 'html',
> '-D', "master_doc=GF4_Users_Guide",
> '-D', 'source_suffix=.rst',
> '-D', 'html_theme=pyramid',
> '-D', 'project=GF4',
> '-D', 'extensions=sphinx.ext.autosectionlabel',
> '-D', 'copyright=Thomas B. Passin 2022',
> '-D', "html_theme_options.sidebarwidth=20em",
>
> # sourcedir, outputdir:
> r'.', r'..\docs']
>
> subprocess.call(cmd)
> else:
> g.es('Cannot find the @rst tree to process', color = 'red')
>
> The key here is providing Sphinx's command line arguments. That happens
> in the block that starts
>
> cmd = [executable, '-m', 'sphinx', '-C',
>
> There are command line parameters for many of the things that would be in
> a config file. The trickiest part is getting the source and build
> directories right. They will be relative to the outline's directory if you
> use relative paths.
>
> For this Sphinx document, the entire rst document is a child of a node
> name @path sphinx. This points to a subdirectory *sphinx* just below the
> outline's directory. The directory structure looks like this:
>
> gf4-docs.leo
> docs
> sphinx
> images
>
>
>
> On Sunday, March 3, 2024 at 2:37:33 PM UTC-5 Geoff Evans wrote:
>
> Obvious question: if I use both Anaconda *and* MacOS (Ventura), which
> part of the Installation instructions supersedes the other? Is Homebrew
> necessary?
> I've still not succeeded with pyqt6.
>
> Unrelated question:
> The traffic on this site is, quite understandably, dominated by the latest
> exciting innovations. So that I'm not sure where to find beginnings any
> more.
> Where do I go to find a gentle introduction to, say, ViewRendered or
> LeoJS: the bit that tells me what might be the payoff if I jump into the
> details of them?
> [Though I probably won't jump in: a nice editor-outliner with clones and a
> literate approach will let me organize my science nicely, alongside jupyter
> notebooks that do the details.
> Maybe the main thing I need to learn, for sharing with colleagues, is
> make-sphinx?]
>
>
--
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/leo-editor/f18e5244-c4f4-440d-9f76-5877df6bee73n%40googlegroups.com.
