Re: Jupyter Notebook support

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view

Re: Jupyter Notebook support

Moved the discussion to the maintainers list.

On 11/28/19 1:59 AM, Juan Pablo Carbajal wrote:

> The example in [4] suffers the disadvantages of the google doc style.
> If you use the numpy style instead multiple outputs are well
> documented [1, subsection 5].
> That said, if the extension doesn't parse numpy-style, then thats
> probably something to discuss with the devs.

Alright, the NumPy-style I did not test in those days.  By comparing the
documentations for the svd() function of NumPy, Octave and Matlab, I
still prefer Octave's current less "technical" design, or maybe I am
more used to it.  Please read on.

>> The 1k pages manual with about 800 docstrings might be another reason
>> not to move away from Texinfo easily.  I can totally understand your
>> motivation, I don't like Texinfo that much either.  But I think it does
>> a good enough job for now, as out-of-the-box alternatives are rare and
>> just introduce new limitations for providing a little more beautiful
>> markup, I guess.
> So, I reckon the texinfo --> sphynx conversion is not tested?
> My greatest problem with texinfo is the amount of work needed to get
> text for manuals with math correctly rendered (unicode to latex
> mappings that need manual tuning), example [2], and the result is far
> from satisfactory. Followed by the fact that highly formatted
> documentation ends up hard to read in plaintext (not rendered),
> defeating the advantages of a markup language.

That is true.  I favor using as plain text as possible for the
docstrings.  No Texinfo, only "natural" markup (maybe a subset of
Markdown) at all.

But as Octave uses the docstrings for the manual as well, it is nice to
have some Markup.  Texinfo for docstrings might be a clumsy, but for
.info-files necessary, choice.  The readability suffers a lot, as you
already mentioned.

>> A more promising approach might be to search for another language with
>> features that Octave documentation needs (functions, scripts, classes,
>> multiple return values, cross-referencing ...) and see how they generate
>> a great looking documentation.  I am also very interesting in such a
>> language/tool.
> Julia --> Markdown [3], and jupyter notebooks/lab
> R --> roxygen2 and Markdown [5,6]
> other languages to check?

Whoops, we started with Jupyter-Notebook support and now I find myself
discussing to overhaul the entire Octave help system.  Maybe a too big
step for now and I would like to narrow the scope again to
Jupyter-Notebook support.  Help system changes might be better suited
for some OctConf.  The great integration of the HTML help output into
the qt-help system by Pantxo was already a big step forward, recently.

Thus how to solve bug #53100 (JSON) might be the next step of my agenda.