Function reference documentation

On the online developer meeting there was a discussion about creating a function reference.

Finally, I managed to get the one hosted on Octave Forge back to work by forking and fixing the generate_html-package, see

I think this is a way to go. The outputs look already promising:

It boils down to

generate_html_manual ("/path/to/octave", "htdocs", ...
                      get_html_options ("octave-forge"));

and a 30 minutes coffee break :coffee:

Thanks to all the creators and maintainers of that package, that it still works “nicely” after only a few bug fixes :+1:

My next steps will be to revisit this package thoroughly, especially update the layout a bit :sweat_smile:

On the Octave side, there are several interactive demos that need to be avoided to run this documentation generation fully automated:

fun = linkprop
Press <enter> to link plots: 
Press <enter> to change color: 
Press <enter> to change linestyle: 

fun = linkaxes
Press <enter> to link axes: 
Press <enter> to change ylim:

fun = colormap
Press a key to continue

fun = uigetdir
fun = uigetfile
fun = uiputfile

Several more widgets

Is there a way to avoid executing those demos?

Another issue is, that the list of indexed functions is generated from the current Octave user manual.

The categories extracted, which is to my plans for the project not desirable to preserve. An alphabetical list of functions might be a good start, as I don’t find the 160 flattened TOC headline categories very helpful in finding a particular function. Opinions?

Is there a way to list all all Octave functions?

If someone is interested in this project too, help is always welcome :slightly_smiling_face:

FWIW for graphics related functions, you’ll find a list of functions (probably outdated) that don’t generate useful images in scrips/testfun/private/dump_demos.m:

...
  ## Remove uigetdir, uigetfile, uiputfile, etc.
  flist = flist(! strncmp (flist, "ui", 2));
  ## Remove linkaxes, linkprops
  flist = flist(! strncmp (flist, "link", 4));
  ## Remove colormap
  flist = flist(! strncmp (flist, "colormap", 8));
...

On my side, I am working on a patch to restructure the manual so that only links and short descriptions appear in the core of the manual, where DOCSTRINGs are currently inserted, and the actual doc strings are in their own page (section) in a dedicated “Function Reference” appendix.

Far-fetched and only tangentially related but I came across a project where (a subset of) Octave was compiled for WebAssembly so that it can run in a browser:

This would allow to run Octave examples directly from the web documentation, client-side.

1 Like

Try

## List of all builtin (C++) functions and m-file functions
funcs = vertcat (__builtins__ (), __list_functions__ ());

This will get whatever is in your PATH so if you want just core Octave you should make sure that you haven’t loaded any packages, included any personal directories with m-files in them, etc.

1 Like

This approach sounds very interesting too. My biggest wish with a function reference is, that you can straight forward “guess” the URL of a function documentation or have a search function (despite external web search engine). Texinfo’s XREF, e.g.

  • https://octave.org/doc/v6.2.0/XREFeigs.html

looks a little ugly with the XREF prefix, but works quite nice. More complicated containers.Map

  • https://octave.org/doc/v6.2.0/XREFcontainers_005fMap.html

is harder to read, guess, and find.

I opened a bug report here.

Can you add your wish to the report?

https://savannah.gnu.org/bugs/index.php?60313#comment3

Done :white_check_mark:

we apparently missed the 2021 Google Season of Docs window. (proposals Feb-Mar, awards announced now-ish). If this sits for a while or is framed out but looks like a ton of work (e.g., to make sure the actual manual is ‘complete’ and useful once all the function docstrings are extracted) this may translate well into a project topic for 2022, which would put a 5-10k $USD technical writer on the task. here’s a list of the types of things the 2020 considers successful: Season of Docs  |  Google Developers

Ones that caught my eye were:
CERN-HSF Restructuring & Streamlining of the Allpix Squared Documentation

Developing Matplotlib Entry Paths

and I thought there was one about a New Developer Onboarding guide but can’t find it.

Last year we tried to apply for GSoD with this wiki page Project - Documentation - Octave, but did not succeed. Maybe it can be overhauled according to other successful applications and we can try to apply again in 2022.