A doc-cache is the file lookfor searches. Octave builds one per directory, resolving every file by its bare name, so a class contributes a single entry and its methods and properties contribute none: they are invisible to lookfor and to everything built on it. This writes them in, choosing exactly the members classdef_texi2html publishes, so a class reads the same way online and in a search.

Run it at the package root, which is where INDEX lives. Every cache below the root is written, one per directory that can be reached by the load path; a +pkg or @class directory has none of its own, since nothing could read one, so its names are written into the cache of the nearest ordinary directory above it.

src is written too, and its cache belongs to it: a build installs the compiled files into an architecture directory of their own, and the cache goes with them, which is why it is not folded into the cache of inst. A DEFUN_DLD help text lives inside the compiled file, so an entry is written for one whose .oct is present and newer than its source, and a stale or missing one stops the run and asks for a build.

'-auto' rebuilds only what changed, taking the work from git: everything that differs from HEAD, staged and unstaged alike, together with the untracked files, since a function written but never committed is invisible to a diff. Where there is no git to ask, or the tree is not a repository, it is ignored with a warning and the whole package is rebuilt.

'-check' writes nothing and reports what would change, so that a tree can be tested for a stale cache without touching it. It may be given together with '-auto', which asks the same question of the changed files alone. Since every docstring is checked as it is parsed, this is also how a package is examined for broken texinfo without writing anything.

options is a pkg_doc_options object. Called without one, the settings are read from doc-options.json at the package root if it carries one, and are the defaults if it does not, so a package’s own conventions are applied by anyone who builds its documentation. The INDEX of the root is read unless the object names another, and it decides what is cached: only the names it lists are written.

status is the number of cache files that changed, or under '-check' would change, and is therefore zero when the tree is current. report is a struct array with one element per cache file touched, carrying the fields 'cache', 'added', 'updated', 'removed', 'changed' and 'findings'. With no output requested the same information is printed.

Every directory below the root is walked, but only those where a doc-cache was written or already stands are reported: most of them hold nothing to cache, and a line saying nothing happened in one would announce a file that is not there.

This is the only form that reports an INDEX entry answering to no file, a single directory being unable to tell one naming a file elsewhere from one naming nothing at all.

See also: folder_texi2cache, classdef_texi2cache, function_texi2cache, package_texi2html, pkg_doc_options, doc_cache_create, lookfor

Source Code: package_texi2cache