Re: [was Promotion of octave ...] Octave material for presentations

[Juan Pablo Carbajal]

> I think this should come as Octave function.  Just run
> grabcode("myjupyter.ipynb") on the JSON-file and import what is
> possible.  That is code sections as usual Octave code in a script file
> and Markdown sections as comments.  The grabbed code is stored in some
> temporary script file, which can in turn be publish()ed again.  The only
> necessary dependency should be jsonencode()/jsondecode(), which do not
> have to be performant at all.
>
Sounds, right to me, much better than what I suggested.

> Yes, I have tested [3] and considered it for one of my Octave projects I
> think three years ago.  After rewriting large parts of the
> documentation, the results where not very satisfying and I dropped this
> approach.  Sphinx is natively written for Python code.  Thus the
> documentation for multiple return arguments does simply look poor
> compared to multiple input arguments, even using [3].  Especially, if we
> want to document multiple ways of return value combinations.  Here an
> example [4].  Additionally, function references were quite "clumsy"
> compared to documenting Python code with Sphinx.  Manual post-processing
> for "see also" links has to be done...  Same experience goes for Doxygen
> which supports Markdown as well.  Both documentation frameworks have
> their target programming languages and this is neither Octave nor Matlab
> :-/  Another promising tools was [5], but the output looks a bit
> "old-school", compared to Sphinx and Doxygen output.
>
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].
That said, if the extension doesn't parse numpy-style, then thats
probably something to discuss with the devs.

[1]: https://numpydoc.readthedocs.io/en/latest/format.html#id8 subsection 5

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

[2]: https://kakila.bitbucket.io/gpemulation/manual.html

> 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 [4,5]

other languages to check?

[3]: https://docs.julialang.org/en/v1/manual/documentation/index.html,
[4]: https://cran.r-project.org/web/packages/roxygen2/vignettes/roxygen2.html
[5]: https://rmarkdown.rstudio.com/articles_intro.html

> Best,
> Kai
>
> [1]: https://pandoc.org/filters.html
> [2]: https://www.gnu.org/software/texinfo/ under "Conversion to/from
> Texinfo"
> [3]: https://github.com/sphinx-contrib/matlabdomain
> [4]:
> https://github.com/sphinx-contrib/matlabdomain/blob/master/tests/test_data/f_example.m
> [5]: https://www.artefact.tk/software/matlab/m2html/