> The example in  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 , 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
>> 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
> Julia --> Markdown , 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.