https://github.com/gnu-octave/pkg-octave-doc
Automatically generate HTML documentation for Octave Packages.
https://github.com/gnu-octave/pkg-octave-doc
Last synced: 2 months ago
JSON representation
Automatically generate HTML documentation for Octave Packages.
- Host: GitHub
- URL: https://github.com/gnu-octave/pkg-octave-doc
- Owner: gnu-octave
- License: gpl-3.0
- Created: 2021-03-24T05:14:00.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2025-10-15T15:43:31.000Z (8 months ago)
- Last Synced: 2025-10-16T12:58:33.353Z (8 months ago)
- Language: MATLAB
- Homepage:
- Size: 1.21 MB
- Stars: 15
- Watchers: 9
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: COPYING
Awesome Lists containing this project
README
# pkg-octave-doc
Create online documentation from Octave help texts (docstrings)
of functions and classes in a package, which can be installed
with **pkg**. The generated pages follow the template of the Octave Packages at
GitHub Pages based on bootstrap 5 and they have similar layout to the older
documentation reference pages at Source Forge. The documentation also includes
the demos that are available. Legacy classes (in `@class/` folders) are processed
as individual functions with separate html pages, `classdef` files are processed
collectively including their public methods in a single html page.
You can find its documentation at [https://gnu-octave.github.io/pkg-octave-doc/](https://gnu-octave.github.io/pkg-octave-doc/).
**Note** that since `pkg-octave-doc (>=0.6.0)` release, Octave (>=9.1) is required.
Moreover, the categories and function files in the side bar are following the same
order in the documented package's INDEX file and the classdef HTML page layout
includes collapsible documentation for all class properties return by calling
`methods ('classname') as well as collapsible documentation only for the methods
(including the constructor) that are present in the classdef file (inherited methods
are ignored).
## Requirements
* The function `function_texi2html` relies on the
[texi2html v1.82](https://www.nongnu.org/texi2html/) software which must be
installed and available to $PATH.
* If `curl` and `tar` are installed and available to $PATH, and an internet connection are available,
the functions' generated pages also include a URL to their respective repository locations. This
feature is only available for packages hosted at GitHub.
## Installation
To install the latest version you need Octave (>=7.2.0) installed on your system. You can install it by typing:
```
pkg install -forge pkg-octave-doc
```
To install the latest development version type:
```
pkg install "https://github.com/gnu-octave/pkg-octave-doc/archive/refs/heads/main.zip"
```
## Usage
Generate a function reference for all functions listed in the INDEX file of an
installed Octave package in the working directory:
```
package_texi2html ("pkg-octave-doc")
```
If you wish to host the generated documentation on GitHub Pages, you need to create a `/docs` folder at the root of your package's repository hosted at Github (or at least mirrored there), run the above command from inside this folder in Octave to generate all necessary files, push the changes and from the repository's interface at GitHub, go to settings, choose `Pages` on the left hand side list (last item in the `Code and automation` category), and in the `Build and deployment` section of the GitHub Pages select:
Source -> Deploy from a branch
Branch -> `main` `/docs` and click `Save`.
You only need to do this once, and the package's website will be automatically updated every time you push a new commit into the package's `/docs` folder.
## Guidelines for TEXIFNO docsstrings
* `@deftypefn` must be used at the beggining of functions and class methods to describe the function's syntax. Consecutive lines with alternative syntaxes must use `@deftypefnx`. Both tags should stricktly follow the pattern showns in the example below in order to be correctly parsed and generate the appropriate HTML code.
```
## -*- texinfo -*-
## @deftypefn {} {} function_name ()
## @deftypefnx {package_name} {} function_name ()
## @deftypefnx {package_name} {@var{out} =} function_name ()
## @deftypefnx {package_name} {@var{out} =} function_name (@var{in})
## @deftypefnx {package_name} {[@var{out}, @dots{}] =} function_name (@var{in}, @dots{})
...
## @end deftypefn
```
**Note** that even when a function does not accept any input arguments, the parentheses `()` after the function name are mandatory.
Also the two sets of curly brackets `{}` before the function name are also mandatory. The first contains the package name (which may be omitted) and the second contains the function's output arguments (including the equal sign operator).
* `@qcode` is converted to `@code` before texi2html processing, so if you want to display a char string it is best to use @qcode{"somestring"}, which will be displayed properly both on Octave's command window and on HTML output. Keep in mind that `@code{}` encloses the content in single quotes in the command window, although they are not displayed in HTML code.
* fields of structures: it is best practice to write them as `@var{structure_name}.@qcode{field_name}` which appears in the command window as `structure_name.field_name` and in HTML as structure_name.field_name. In bootstrap 5, the `` tag is not highlighted and it looks better than here :smiley:.
* Avoid nesting `@itemize` and `@multitable` blocks because they are not parsed correctly by `texi2html`. You can achieve the same visual result by segmenting them.
* Table columns in HTML use dynamic width, so if you wish to maintain the required width for better visualization, add extra empty `@tags` inbetween.
For example:
````
@multitable @columnfractions 0.35 0.65
@item text @tab text
````
can be converted to
````
@multitable @columnfractions 0.33 0.02 0.65
@item text @tab @tab text
````
* Make sure that `@deftypefn` and `@deftypefnx` tags have a white space before them. This is especially important for help strings in oct files (in .cc code) where we don't use ## for initiating a comment line.
For example:
in .m files
````
## -*- texinfo -*-
## @deftypefn {pkg-octave-doc} {} function_texi2html (@var{fcnname}, @var{pkgfcns}, @var{info})
##
````
in .oct files
````
DEFUN_DLD (libsvmread, args, nargout,
"-*- texinfo -*- \n\n\
@deftypefn {statistics} {[@var{labels}, @var{data}] =} libsvmread (@var{filename})\n\
\n\
\n\
This function ...
````
* Small docstrings containing a single line of help text after the `@deftypefn` tag must have an additional empty line before `@end deftypefn` in order to be parsed correclty. For example, the following docstring
````
## -*- texinfo -*-
## @deftypefn {RTree} {@var{n} =} rect_size ()
##
## The size @var{n} in bytes of a rectangle.
## @end deftypefn
````
must be
````
## -*- texinfo -*-
## @deftypefn {RTree} {@var{n} =} rect_size ()
##
## The size @var{n} in bytes of a rectangle.
##
## @end deftypefn
````
in order to be properly formatted in final HTML code.
* `@math{}` texi tags are converted to `` tags in HTML and their contents are scanned for `x` and `*` characters, which are replaced by `×` in order to properly display the multiplication symbol. Make sure that lower case `x` within the `@math{}` tags is explicitly used for denoting multiplication and it is not used for anything else (e.g. variable name). This feature, introduced in release 0.4.7, only affects the contents of `@math{}` texi tags.
* At the moment, `function_texi2html` can handle a signle `@seealso{}` tag. Make sure that there is only one `@seealso{}` tag inside each function's docstring located at the very end just before the `@end deftypefn` texinfo closing statement. Functions listed therein that belong to the same package are also linked to their individual function pages.
* `@tex` tags must only contain latex mathematical expressions enclosed with `$$` identifiers, such as in `$$ ... $$`. Math delimiters `\(...\)` are also processed in `@tex` blocks.
## Guidelines for classdef documentation
Classdef documentation and demos are handled separately in more specialized manner. For each classdef file, a single HTML page is generated containing collapsible items for the documentation of each public property and methods as well as any demos that may be present in the classdef file. Class properties, methods (including the constructor), and demos are grouped together and they follow the same order as they appear in the classdef file.
Top level classdef documentation and classdef properties should use the `@deftp` tag for name declaration instead of the `@deftypefn` tag used in syntax declaration of functions and class methods. Only a single line should be used for name declaration as shown in the example below.
```
classdef class_name
## -*- texinfo -*-
## @deftp {package_name} class_name
##
## A class that does something.
##
## More info about it...
##
## @end deftp
properties
## -*- texinfo -*-
## @deftp {class_name} {property} property_name
##
## Property short description
##
## More info about it...
##
## @end deftp
property_name = []
endproperties
endclassdef
```
The first sentence in the docstring of a property or a method is used as a short description in the collapsible item. The respective description for class demos is taken from the top comment lines of each demo block (if available), otherwise the command line for calling the particular demo is used as a default.
Any demos documenting the functionality of a property or method have to be saved in an external file in order to be included inside the respective collapsible item after the help documentation in the same manner it is done for functions. For this feature to work, you must be able to call the particular demos with the same typing convention as you do with the help docstrings.
## TODO
1. Write a C++ implementation for parsing texinfo to html to relax the
dependency on the rather outdated `texi2html` software.
3. Rewrite `build_DEMOS` function so that DEMO documentation includes
the console output and generated figures just after the line of code
that produces the output instead of accumulating all the output and
figures after the DEMO code block. This should help larger DEMO blocks
to be more intuitively presented in the generated documentation.
## Further notes
Albeit completely overhauled, this is a fork of the
[generate_html](https://packages.octave.org/generate_html) package previously
used for Source Forge reference pages.