[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Jupyter Notebook support
From: |
Kai Torben Ohlhus |
Subject: |
Re: Jupyter Notebook support |
Date: |
Thu, 28 Nov 2019 18:24:11 +0900 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.2.1 |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- Re: Jupyter Notebook support,
Kai Torben Ohlhus <=