Re: Jupyter Notebook support

[Kai Torben Ohlhus]

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.

  https://docs.scipy.org/doc/numpy/reference/generated/numpy.linalg.svd.html

  https://octave.org/doc/v5.1.0/XREFsvd.html

  https://www.mathworks.com/help/matlab/ref/double.svd.html


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

Best,
Kai


[1]: https://numpydoc.readthedocs.io/en/latest/format.html#id8
[2]: https://kakila.bitbucket.io/gpemulation/manual.html
[3]: https://docs.julialang.org/en/v1/manual/documentation/index.html
[4]:
https://github.com/sphinx-contrib/matlabdomain/blob/master/tests/test_data/f_example.m
[5]:
https://cran.r-project.org/web/packages/roxygen2/vignettes/roxygen2.html
[6]: https://rmarkdown.rstudio.com/articles_intro.html
[7]: https://savannah.gnu.org/bugs/?53100