Octave Package Documentation: package_texi2html

### Function Reference: `package_texi2html`

pkg-octave-doc: package_texi2html (pkgname)
pkg-octave-doc: [pkgfcns, info] = package_texi2html (pkgname)

Generate HTML pages for an entire package.

`package_texi2html` takes a single input argument, pkgname, which is a char string with the package’s name whose HTML documentation need to be generated. The function considers the current working path as the root directory of the built pages. It creates an `index.html` page with the available functions (and their subdivision into separate categories) of the package according to its INDEX file. Although the INDEX file (if absent) is automatically generated during the package’s installation, it is best practice to include one in the package’s source so there is full comtrol of the categorization among the functions. Individual functions HTML pages area generated with `function_texi2html`.

The generated pages follow the template of the Octave Packages GitHub Pages based on bootstrap 5 and the generated HTML code is based on the `index_template.html` and `default.html` layouts.

For packages whose repository is available at GitHub, individual URLs to each function’s location within the reposity are retrieved and used to add a link to source code in each function’s page. This requires an internet connection and `git` installed and available to the system’s `$PATH`. If not available, the source code link is omitted and the functions’ HTML pages are generated without it.

For the `package_texi2html` to work, the `texi2html` command line tool, version 1.82, must be installed and available to the system’s `$PATH`.

Optionally, `package_texi2html` can return two output arguments, namely pkgfcns and info, which are necessary for the `find_GHurls` and `function_texi2html` functions. In such case, the HTML pages generation is skipped. This is useful for building individual function pages without the need to regenerate the package’s entire documentation.

Examples:

     [pkgfcns, info] = package_texi2html ("pkg-octave-doc");
     pkgfcns = find_GHurls (info.PKG_URL, pkgfcns);
     function_texi2html ("find_GHurls", pkgfcns, info);

Returning arguments:

- pkgfcns is a Nx2 cell array containing the package’s available functions (1st column) and their respective category (2nd column).
- info is a structure with the following fields:

  Field Name | Description
  --- | ---
  `PKG_URL` | The URL to the package’s repository at GitHub.
  `PKG_ICON` | The relative reference to the package’s logo image which must be either in .svg or .png format and it is located in the newly created `assets/` folder inside the working directory.
  `PKG_NAME` | The package’s name (e.g. "pkg-octave-doc")
  `PKG_TITLE` | The package’s title (e.g. "Octave Package Documentation")
  `OCTAVE_LOGO` | The relative reference to Octave’s logo, also located inside the `assets/` folder.

See also: function_texi2html, find_GHurls, build_DEMOS

Source Code: package_texi2html