Categories &

Functions List

Class Definition: pkg_doc_options

pkg-octave-doc: pkg_doc_options

Settings for the documentation builders of a package.

A pkg_doc_options object carries the location of a package’s INDEX file, how much a run prints, and the severity of each rule the documentation builders check a docstring against. Every property is public, so the object is itself the list of what a maintainer may configure, and each carries its own help text describing what it controls.

opts = pkg_doc_options () returns an object holding the default settings. opts = pkg_doc_options (filename) reads a JSON file over those defaults, taking a bare name in the current directory or an absolute path anywhere. Anything in it this release cannot use, whether a key that is not a property or a value a property will not take, is reported and passed over, and the rest of the file is read: a settings file outlives the release that wrote it, and one written for a later release must not stop a documentation build under an earlier one.

It is a value class, so an assignment returns a modified copy:

 
 opts = pkg_doc_options ();
 opts.BodyColumns = 80;
 opts.SeealsoInMember = 'error';

save_to_json writes the settings back, storing only the properties that differ from the defaults, so a rule added in a later release cannot be pinned to an old value by a file already written.

A severity is 'error', 'warning' or 'off'. It says how a finding is reported and never whether a run continues: a docstring defect is reported, counted and returned, and the run goes on.

See also: package_texi2cache, folder_texi2cache, classdef_texi2cache, function_texi2cache

Source Code: pkg_doc_options

The pkg_doc_options class contains the following properties:

Severity of a @deftypefn or @deftypefnx header broken across two or more lines, which makeinfo does not accept and which therefore breaks help for the whole docstring. Defaults to 'error'.

Severity of an @end command carrying body text on the same line, as in @end itemize and more text, which is not a valid closing command. Defaults to 'error'.

Severity of a literal @ that is neither doubled nor the start of a known texinfo command, as an anonymous function written inside @code without doubling it. Defaults to 'error'.

Severity of an unbalanced brace in a docstring, which swallows the text following it or ends a command early. Defaults to 'error'.

Severity of a block command, such as @itemize or @example, opened and never closed by a matching @end. Defaults to 'error'.

Severity of a category label that names no class in the package, or that is not an identifier at all, as a literal format specifier left in the text. Defaults to 'warning'.

Severity of a public function or class member with no help text, for which help answers that it is undocumented and which no cache entry can be built for. Defaults to 'warning'.

Width limit of a docstring body line, specified as a positive integer giving the column past which a line is reported, or as 'off', the default, which does not check the width at all. A @deftypefn or @deftypefnx header is never measured, being allowed to run over.

This is a house rule of the packages maintained alongside this one rather than a defect, which is why it is off unless a package asks for it.

Severity of a @seealso command in the help text of a class member. Defaults to 'off', this being a house rule of the packages maintained alongside this one rather than a defect.

Location of the package’s INDEX file, specified as a character vector holding an absolute path, as '' to use no INDEX even where one exists, or as [], the default, to leave it unspecified.

The three states are distinct because INDEX decides what a whole scope caches: left unspecified, package_texi2cache reads the INDEX of the package root it is standing in, whereas '' switches that off and caches whatever the tree holds.

Severity of a documented name found in the tree but absent from the package’s INDEX, which leaves it out of the published documentation and, where INDEX decides what is cached, out of the doc-cache as well. Defaults to 'warning'.

Severity of an INDEX entry that answers to no file in the package, which is reported only by a run covering the whole package, a single directory being unable to tell such an entry from one naming a file elsewhere. Defaults to 'warning'.

Severity of a run that reads INDEX finding none to read. Defaults to 'warning', and is the rule to switch off for a package that deliberately ships without an INDEX.

How much a run prints, specified as 'all', the default, which prints every finding and then the summary; 'summary', which prints the summary alone; or 'none', which prints nothing.

Findings are returned in the report at every setting, so 'none' is for a programmatic caller rather than a way of hiding them.

The pkg_doc_options class offers the following public methods:

pkg_doc_options: obj = pkg_doc_options ()
pkg_doc_options: obj = pkg_doc_options (filename)

obj = pkg_doc_options () returns an object holding the default settings.

obj = pkg_doc_options (filename) reads a JSON file over those defaults, taking a bare name in the current directory or an absolute path anywhere. The file holds only the settings a package differs from the defaults in, which is what save_to_json writes. Anything the running release cannot use, a key that is not a property or a value a property will not take, is reported and passed over while the rest of the file is read.

pkg_doc_options: save_to_json (obj, filename)

save_to_json (obj, filename) writes the properties of obj that differ from the default settings to filename, taking a bare name in the current directory or an absolute path anywhere. An object holding nothing but defaults writes an empty JSON object.

Only the differences are stored, so a property added in a later release is not pinned to an old value by a file already written, and the file stays readable as a statement of what a package asks for.