Unable to create Leo's Documentation locally

[Viktor Ransmayr]

Should it still be possible to create Leo's Documentation locally on Linux from "LeoDocs.leo"?

I'm failing to do so inside a Debian 11 - based VM.

I verified this both on the master branch / PyPI - and - devel branch / from GitHub ...

Below are my logs w/ more details.

With kind regards,

Viktor

###

Open the 'correct' (see below) outline containing Leo's documentation - Not OK - See "Log-001".

* unl:///home/user/PyVE/PyPI/Leo/lib/python3.9/site-packages/leo/doc/LeoDocs.leo#Leo%27s Documentation

Execute the 'make-sphinx' button on the "Leo's Documentation" node in this outline - Not OK - See "Log-002".

Close & re-open this outline in '~/PyVE/GitHub/Leo'.

Open the 'correct' (see below) outline containing Leo's documentation - OK - See "Log-003".

* unl:///home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/LeoDocs.leo#Leo%27s Documentation

Execute the 'make-sphinx' button on the "Leo's Documentation" node in this outline as well - Not OK - See "Log-004".

### Log-001

    Leo Log Window
    Leo 6.7.2
    Python 3.9.2, PyQt version 5.15.2
    linux
    can not open /home/user/PyVE/PyPI/Leo/lib/python3.9/site-packages/docs/redirect_index.html
    can not open /home/user/PyVE/PyPI/Leo/lib/python3.9/site-packages/docs/index.html
    read 10 files in 0.48 seconds
    read outline in 0.61 seconds

### Log-002

    Run `make-sphinx` from `gh-pages` branch

### Log-003

    Leo Log Window
    Leo 6.7.2-devel
    Python 3.9.2, PyQt version 5.15.2
    linux
    read 10 files in 0.49 seconds
    read outline in 0.67 seconds

### Log-004

    Run `make-sphinx` from `gh-pages` branch

[Edward K. Ream]

On Fri, Mar 17, 2023 at 12:59 AM Viktor Ransmayr <viktor....@gmail.com> wrote:

Should it still be possible to create Leo's Documentation locally on Linux from "LeoDocs.leo"?

Thanks for this report. See issue #3207.

Edward

[Thomas Passin]

The following script will build everything except the slides.  Either it needs to be run from the leo/doc directory or the path needs to be added to the script instead of the "." in the last line:

#see https://github.com/leo-editor/leo-editor/issues/1566
import sys
import subprocess
pyexe=sys.executable
cmd=[pyexe,'-m','sphinx','-C',
'-D', 'master_doc=html/leo_toc',
'-D', 'source_suffix=.html.txt',
'-D', 'html_theme=sphinx_rtd_theme',
'-D', 'project=LeoDocs',
'.', r'c:\temp\result']

subprocess.call(cmd)

To use the theme, IIRC, it needs to be installed from PyPi first.  Run the script with the usual CNTL-b.

I first worked this up in 2020.  I just now tried it out to see if it still works by pasting it into a new node at the top of the LeoDocs outline.  Change the "result" location in the last line to suit yourself.

Using the full process using the outline's own button presumably will add some features - I'm not sure what - but until it gets fixed this will do the job.

[Edward K. Ream]

On Fri, Mar 17, 2023 at 8:39 AM Thomas Passin <tbp1...@gmail.com> wrote:

The following script will build everything except the slides. 

Thanks for this. Still, `@button make-sphinx` should work without complaint.

Edward

[Viktor Ransmayr]

Hello Thomas

tbp1...@gmail.com schrieb am Freitag, 17. März 2023 um 14:39:46 UTC+1:

The following script will build everything except the slides.  Either it needs to be run from the leo/doc directory or the path needs to be added to the script instead of the "." in the last line:

#see https://github.com/leo-editor/leo-editor/issues/1566
import sys
import subprocess
pyexe=sys.executable
cmd=[pyexe,'-m','sphinx','-C',
'-D', 'master_doc=html/leo_toc',
'-D', 'source_suffix=.html.txt',
'-D', 'html_theme=sphinx_rtd_theme',
'-D', 'project=LeoDocs',
'.', r'c:\temp\result']

subprocess.call(cmd)

To use the theme, IIRC, it needs to be installed from PyPi first.  Run the script with the usual CNTL-b.

I first worked this up in 2020.  I just now tried it out to see if it still works by pasting it into a new node at the top of the LeoDocs outline.  Change the "result" location in the last line to suit yourself.

I used a slightly simpler version, since I did not want to add any dependency & make it non-windows specific:

import sys
import subprocess
pyexe = sys.executable
cmd = [pyexe, '-m', 'sphinx', '-C',

          '-D', 'master_doc=html/leo_toc',
          '-D', 'source_suffix=.html.txt',

          '-D', 'project=Leo Docs',
          '.', 'result']

subprocess.call(cmd)

It works kind of OK - but - did reveal, that Leo's Documentation Outline is still assuming that development & release work is done on Windows ...

Below are my logs w/ more details.

With kind regards,

Viktor

###

Execute this button on the "Leo's Documentation" node of the outline - OK - See "Log-002".

* Check out the result ...
* file:///home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/result/html%5Cleo_toc.html <- ?
* -> file:///home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/result/html/leo_toc.html <- !
* ... and compare it with
* https://leo-editor.github.io/leo-editor/leo_toc.html

### Log-002

    (Leo) user@debian-leo-study-vm:~/PyVE/GitHub/Leo/leo-editor/leo$
    (Leo) user@debian-leo-study-vm:~/PyVE/GitHub/Leo/leo-editor/leo$ Running Sphinx v4.3.1
    loading pickled environment... done
    building [mo]: targets for 0 po files that are out of date
    building [html]: targets for 49 source files that are out of date
    updating environment: [config changed ('project')] 133 added, 0 changed, 0 removed
    reading sources... [100%] html/writingPlugins                                  
    /home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/html/intermediatetopics.html.txt:7: WARNING: toctree contains reference to nonexisting document 'html/unitTesting'
    /home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/html/leo_toc.html.txt:24: WARNING: toctree contains reference to nonexisting document 'html/toc-more-links'
    looking for now-outdated files... none found
    pickling environment... done
    checking consistency... /home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/html/FAQ.html.txt: WARNING: document isn't included in any toctree
    /home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/html/cheatsheet.html.txt: WARNING: document isn't included in any toctree
    /home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/html/glossary.html.txt: WARNING: document isn't included in any toctree
    /home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/html/history.html.txt: WARNING: document isn't included in any toctree
    /home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/html/leoLinks.html.txt: WARNING: document isn't included in any toctree
    /home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/html/screen-shots.html.txt: WARNING: document isn't included in any toctree
    /home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/html/screencasts.html.txt: WARNING: document isn't included in any toctree
    /home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/html/slides.html.txt: WARNING: document isn't included in any toctree
    /home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/html/slides/basics/basics.html.txt: WARNING: document isn't included in any toctree
    /home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/html/slides/clones-and-views/clones-and-views.html.txt: WARNING: document isn't included in any toctree
    /home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/html/slides/external-files/external-files.html.txt: WARNING: document isn't included in any toctree
    /home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/html/slides/minibuffer/minibuffer.html.txt: WARNING: document isn't included in any toctree
    /home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/html/slides/scripting-leo/scripting-leo.html.txt: WARNING: document isn't included in any toctree
    /home/user/PyVE/GitHub/Leo/leo-editor/leo/doc/html/what-is-new.html.txt: WARNING: document isn't included in any toctree
    done
    preparing documents... done
    writing output... [100%] html/writingPlugins                                    
    generating indices... genindex done
    writing additional pages... search done
    copying images... [100%] html/screen-shots/leo-workbook.png                    
    copying static files... done
    copying extra files... done
    dumping search index in English (code: en)... done
    dumping object inventory... done
    build succeeded, 16 warnings.

    The HTML pages are in result.

[Viktor Ransmayr]

Hello Thomas,

I should have made the issue more explicit ...

The problem is that  Leo's Documentation Outline is still using backslashes "\" , which are kept / visible even on Linux, i.e.

###

user@debian-leo-study-vm:~/PyVE/GitHub/Leo/leo-editor/leo/doc/result$ ls
 genindex.html                    'html\tutorial-basics.html'
 html                             'html\tutorial.html'
'html\cheatsheet.html'            'html\tutorial-pim.html'
'html\coloring.html'              'html\tutorial-rst3.html'
'html\console-gui.html'           'html\tutorial-scripting.html'
'html\debuggers.html'             'html\tutorial-tips.html'
'html\emacs.html'                 'html\vimBindings.html'
'html\FAQ.html'                   'html\writingPlugins.html'
'html\IPythonBridge.html'          _images
'html\leoBridge.html'              objects.inv
'html\leonine-world.html'          search.html
'html\leo_toc.html'                searchindex.js
'html\leo-university.html'         _sources
'html\scripting-miscellany.html'   _static
user@debian-leo-study-vm:~/PyVE/GitHub/Leo/leo-editor/leo/doc/result$

###

With kind regards,

Viktor

[Thomas Passin]

On Saturday, March 18, 2023 at 1:28:05 PM UTC-4 viktor....@gmail.com wrote:

Hello Thomas

....

I used a slightly simpler version, since I did not want to add any dependency & make it non-windows specific:

import sys
import subprocess
pyexe = sys.executable
cmd = [pyexe, '-m', 'sphinx', '-C',

          '-D', 'master_doc=html/leo_toc',
          '-D', 'source_suffix=.html.txt',

          '-D', 'project=Leo Docs',
          '.', 'result']

subprocess.call(cmd)

I originally used "result" as the output directory too.  I changed to a temp directory to keep it out of the LeoDocs tree, thinking it would simplify commits if the output were not in there.  But I suppose a lot of  the intermediate files end up in the LeoDocs directories anyway, so it probably doesn't matter.