Finish support restructured text (rST) in leoRst.ts

[boltex]

Most of leoRst.ts is implemented, but the following lines importing the 3rd party libraries to handle restructured text (rST) in leoRst.py can not easily be reproduces in leoRst.ts, preventing the whole of the rst functionality to run:

# Third-part imports...
try:
    import docutils
    import docutils.core
    from docutils import parsers
    from docutils.parsers import rst
except Exception:
    docutils = None  # type:ignore

Find some libraries to do the equivalent, or implement this functionality from scratch (or via transliterating the python sources) to enable the rst functionality in LeoJS.

[ranvik14]

I did a quick search for rST & JavaScript and found the following GH references:

• https://github.com/docutils-js/docutils-js
• https://github.com/seikichi/restructured

PS: I have seen the 'help wanted' tag - but - don't feel that I would be able to help with an implementation in JS/TS. PPS: I'll follow this issue very carefully ;-)

[edreamleo]

@boltex I found the same links. Perhaps you could say hello to their projects :-)

[boltex]

I'll also explore what Thomas said on the google group:

The rst3 command can operate without using docutils. There's a setting about that, rst3-call-docutils. I have used rst3 for many sphinx documents without needing to use docutils. Sphinx itself will use it, but you run as an external executable outside of the rst3 command.

I'm not sure what using docutils gets you, but it seems to me that you could get the command working without docutils, and if someone changes the settings to ask for them, output a warning message about it. (I think that it's connected with another setting for writing intermediate files, but I'm not sure of that. Anyway, I don't use it.)

[edreamleo]

@boltex

LeoJS doesn't need docutils in Typescript. LeoJS probably does need something like sphinx-js.

docutils

Unless I am seriously mistaken, LeoJS does not need docutils. Indeed, LeoDocs.leo contains these settings:

@bool rst3_call_docutils = False
@bool rst3_write_intermediate_file = True

rst.write_docutils_files will never call docutils when @bool rst3_call_docutils is False.

rst.writeIntermediateFile is straightforward and uses no libraries.

The make-sphinx button

LeoDocs.leo uses the @button make-sphinx script to generate html files. The script does roughly the following:

• Writes intermediate files.
• Calls g.execute_shell_commands(['make html',]).

On Windows, make.bat and Makefile reside in the leo/doc/html folder.

Summary

LeoJS probably needs sphinx-js. sphinx-js looks good at first glance. YMMV.

You may also want to transliterate the make-sphinx script in LeoDocs.leo.

[tbpassin]

With Leo, Sphinx is called as a command-line program by a user script or command, not by Leo code. So LeoJS could do the same thing. Sphinx would have to be installed (along with Python) outside of VSC, and the LeoJS user would write a command to run it as a command line program.

It should not be necessary to find a Javascript port of Sphinx.

[boltex]

@edreamleo about sphinx-js : sadly, its not a javascript implementation of sphinx, it's just a tool for pulling JSDoc-formatted documentation comments from javascript/typescript source files, and turn that into reStructuredText pages.