FYI: Simplified installation instructions

[Edward K. Ream]

Leo's "devel" and "6.7.8" branches now contain simplified installation instructions. These instructions are now live on Leo's website.

A few changes turned into general housecleaning:

- Greatly simplified the Getting Started and Installation pages.

- Removed all "download" links. The "installation" instructions suffice!

- Use PyPi links for most dependencies.

- Moved several obsolete related FAQ and HowTo entries to the "archive" node in LeoDocs.leo.  I'll delete these archive entries in the release after 6.7.8.

- Simplified the instructions (in LeoDocs.leo) about generating the documentation:

  Just use the make-sphinx button from the gh-pages branch!

All questions and comments are welcome.

Edward

[Geoff Evans]

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?]

geoff

[Thomas Passin]

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

[Thomas Passin]

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!

[Edward K. Ream]

On Sun, Mar 3, 2024 at 1:37 PM Geoff Evans <gtev...@nl.rogers.com> wrote:

Obvious question: if I use both Anaconda and MacOS (Ventura), which part of the Installation instructions supersedes the other?  Is Homebrew necessary?

I don't know. The new installation instructions have not changed any of the MacOS stuff.

I recommend installing via GitHub if possible on any platform. That should be easier now.

Edward

[HaveF HaveF]

Nowadays, I always use pipx install or update leo(instead of conda env)

install like:
pipx install leo

update from the source:

git clone .......

cd .......

git pull

pipx inject leo /Users/mac/Desktop/proj/leo-editor

[Edward K. Ream]

Excellent. This recipe is so much better than the existing one.

Googling pipx yields this page, so perhaps the MacOS recipe should be:

brew install pipx
pipx ensurepath
pipx install leo

What do you think?

Edward

[HaveF HaveF]

pipx install leo

pipx is a general approach to install python applications, not only for Mac. I like it because it is not messing up my python environment, if I also need to install something in this environment, I just need
pipx inject leo <dependencies>
That's it.

update cmd is:

pipx inject leo <local leo-editor repo path>

Maybe it should be considered an extra trick rather than specific to the platform