Finish support restructured text (rST) and sphinx 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 ;-)

[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.

[boltex]

Some follow-up about this single missing features of LeoJS: rst support

@edreamleo @tbpassin I don't intend to cover leoDocs and its specific generation-scripts in LeoJS. I just intended to have leoRst.py converted, and functional.

(I'll do a complete refactor/rewrite of the current Leo documentation in a modern web framework very soon 😄 )

@ranvik14 Sadly, docutils-js, restructured (and docutils-typescript) are unfinished projects which would need almost more work to use than translating docutils from python to typescript. (I tried compiling and using them. It's working, but with many bugs and many components and directives of rst markup are unsupported or missing)

What would be needed is some 'light' version of docutils for js or ts... Something that just converts from string to string, leaving the file i/o to the upstream caller. like the original author of docutils-js, @kaymccormick, intended, etc...

Don't know how much rst support is worth for leonistas in general. I hope to someday have the time to make this part of LeoJS working!

[edreamleo]

@boltex I agree with your choice not to assign a milestone to this issue.

[tbpassin]

I don't think it needs to be difficult if you are willing to call an external program. The way I create RsT documentation with LeoPY is with the rst3 command and Sphinx. I don't use docutils for it at all:

@bool rst3-call-docutils = False

The rst3 command creates the source tree for Sphinx to process. Then I call Sphinx as an external program using a script in another node.

Yes, to use Sphinx one has to install Python. To run Asciidoc one might install Ruby to run the Ruby Asciidoc processor. I think that's all right. VR3 can use the Ruby Asciidoc processor, and of course it has to be installed. If users want the capability, let them install Sphinx, which does entail installing Python.

[ranvik14]

@boltex : For my use-case the option described by @tbpassin would be sufficient.

[tbpassin]

There's also an RDoc Ruby command line documentation generator. I don't know what its source tree has to look like, and it uses Markdown, but one could write a command similar to rst3 for it.

But since we already have the rst3 command and Sphinx does a nice job, might as well stick with it.

[ranvik14]

@boltex : Now that version 1.0 of LeoJS is out of the door, I hope you find some time for looking into this issue again.

I spent a bit more time to search for other projects providing rST - and/or - Sphinx support.

I believe the following ones are worth to be checked out:

[a] RST Compiler @ NPM

• https://www.npmjs.com/package/rst-compiler
• -> https://github.com/Trinovantes/rst-compiler/releases/tag/v0.2.10
• --> https://github.com/Trinovantes/rst-compiler/
• ---> https://trinovantes.github.io/rst-compiler/

[b] reStructuredText @ VS Marketplace

• https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext
• -> https://github.com/vscode-restructuredtext/vscode-restructuredtext/releases/tag/190.4.0
• --> https://github.com/vscode-restructuredtext/vscode-restructuredtext/
• ---> https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext

[c] mozilla/sphinx-js @ GitHub

• https://github.com/mozilla/sphinx-js/blob/master/README.rst
• -> https://github.com/mozilla/sphinx-js/releases/tag/3.2.2
• --> https://github.com/mozilla/sphinx-js/
• ---> https://pypi.org/project/sphinx-js/

All three projects are active & have released new versions not that long ago ...

[boltex]

Thanks to all who have posted to this thread.

About LeoDocs.leo: LeoDocs is not part of LeoJS. Also, like Thomas said, in LeoDocs.leo, Sphinx is called as a command-line program by a user script or command. This could be done in LeoJS without any problems by a user wanting to use sphinx. There are examples of using OS commands in the LeoJS sample scripts repository. See https://github.com/boltex/scripting-samples-leojs

Maybe Sphinx-JS should be included in LeoJS as a library available to Leo Scripts. I'll try to include it in the next release as many Leonistas seem to be fond of that tool 😄

About docutils-js: This was intended to be a port of python's docutils to javascript,but sadly it's author Kay McCormick
past away earlier this year.

About rst-compiler: This seems to be an equivalent of docutils ! It's brand new from this month! I'll take a look at it in more details right now! Thanks @ranvik14 !!! Greatly appreciate your continuous research!

I'll keep posting details about what I find. (this is a bit harder for me because although I've been using Leo since 2002, I've never done anything with rst nor sphinx ever, so I'm a total noob when it comes to those things.)