pkg-octave-doc-0.8.6

Fixes the typography written into a doc-cache, which kept lookfor from finding text across an apostrophe or an ellipsis, and a false warning on the methods of old-style classes.

Bug fixes

• A doc-cache holds typography as the ASCII it was written in, not as HTML entities: tree’s, … and × read tree's, ... and x again, so lookfor -all finds text across them. Rebuild the caches to pick it up.
• A method in an @class folder may be labelled with its class, as a classdef member is, without a CategoryLabel warning from package_texi2cache, function_texi2cache or check_texi_docs.

pkg-octave-doc-0.8.5

A class whose superclass lives elsewhere in the package gets its doc-cache again, cached help texts keep their punctuation in place, and help pages are valid HTML with the source code link written once.

Bug fixes

• package_texi2cache no longer fails with class not found on a class whose superclass lives in another directory of the package. The package tree is on the load path for the whole run, and the path is left as it was.

• A doc-cache no longer spaces punctuation off marked-up text: alpha , and ( x ) read alpha, and (x) again. Rebuild the caches to pick it up.

• The signature lines and the class title of a help page are valid HTML. They were written as <code><h5>...</code></h5> inside a <dl> holding no <dd>. Pages look the same; in the Qt help the signatures are larger, in regular weight, with the name in bold.

• A help page whose text holds a table no longer repeats the "Source Code" link after every table; it is written once, at the end. Documentation built with 0.7.2 or later wants a rebuild to drop the extra links.

pkg-octave-doc-0.8.4

Cross-references link to their pages again, and a doc-cache built in the same session no longer breaks the demos of a later HTML build.

Bug fixes

• A cross-reference to a function or class the package documents (@seealso, @xref, @ref, @pxref) links to its page again. Since 0.8.2, package_texi2html linked every such name to a garbled form of its source code URL, which resolves to nothing, so documentation built with 0.8.2 or 0.8.3 wants a rebuild.

• Building a doc-cache with package_texi2cache, folder_texi2cache or classdef_texi2cache no longer breaks the first demo of a class documented later in the same session. The class stayed bound to the directory the cache was built in, so its private functions could not be found and the demo rendered an error.

pkg-octave-doc-0.8.3

Find-in-page reaches the text inside collapsed panels, source code links name the commit the documentation was built from, and five defects in how a class file is read and reported are fixed.

Incompatible change

A class page anchors its constructor after its class, Class_Class, where it was the fixed name colapsibleConstructor. A link to a constructor on a page built before this release no longer resolves, so a class page must be rebuilt for its own links to work.

Improvements

• The browser's find-in-page reaches the text inside a collapsed member, group or example panel and opens the panel on a match. Where the browser does not support it the page is unchanged.

• A source code link names the commit the documentation was built from, where it named the default branch, so it keeps pointing at the code the page describes. The commit is named only where the file on GitHub and the installed file hold the same text; otherwise the branch is named as before.

• A method page's source code link lands on the line that declares the method, where it landed at the top of a class file that may hold dozens of them. A link is anchored only where it names a commit.

Bug fixes

• A class declaring its methods at the first column was documented with none of them, on its html page and in its doc-cache entries alike, and nothing was reported. The declarations were searched for with a leading space, so one standing at the first column was invisible.

• An old style class reached the classdef renderer, which it left through an unguarded properties call. What a source file declares now decides which route documents a name, so its constructor and its methods are documented as the functions INDEX names them.

• A class that failed to render was published as a plain function page with nothing reported, one try having answered both "this is not a class" and "this class did not render". The class is named now and the build carries on.

• A classdef carrying a syntax error was reported as not being a classdef, discarding what Octave had said of it. The reason the file gave is reported now, naming the line that fails.

• A reference to a method a class inherits was made a link to an anchor no page carries, and on a class rendered with method groups to a page that was never written. Such a name renders as plain text now; an inherited property is documented and still resolves.

pkg-octave-doc-0.8.2

Cross-references to class members now resolve, and what a class member is owed as documentation is stated and enforced.

Incompatible change

The collapsible holding a property or a method on a class page is named after the member, Class_member, where it was numbered by position, collapseMethod3. A link to an anchor of an earlier build no longer resolves, so a class page must be rebuilt for its own links to work.

Improvements

• An @seealso, @xref, @ref or @pxref naming a class method or property links to it, whether the name is bare, qualified, namespaced or an old style @class/member. A method of a grouped class links to its own page; a property, and a method of a flat class, link to the class page and to the collapsible holding them, which the page expands and scrolls to. Only names the package documents resolve, so a hidden member and a class absent from INDEX are left as text.

• What a class member is owed is stated in the README and applied by the builders: a docstring on every public member and on a constructor whether or not it is hidden; a doc-cache entry for the class, for its constructor where the file declares one, and for what methods and properties report; and a published page for nothing hidden at all. A hidden constructor is therefore documented and cached but not published, and is the only member of that kind.

• A class page in the Qt help file names every property and method the class holds, each linked to its own anchor and given the first sentence of its help text. It listed the titles of its subpages, which the contents tree already shows.

Bug fixes

• A constructor declared in a methods (Hidden) block was published: rendered on the page of a flat class, and given a page of its own on a grouped one.

• A class inside a namespace listed its constructor among its public methods and rendered no constructor section.

• A class declaring no constructor was reported as MissingDocstring for a member that does not exist, and the entry of a constructor declared Hidden was written only because every class was given one. The class file now decides.

pkg-octave-doc-0.8.1

Patch release over 0.8.0, fixing one defect in the doc-cache route.

An INDEX line carrying several names is read as several names

Octave's own INDEX parser tokenises each function line, so several names on one line is a supported format. The doc-cache builders took the whole line as one name. That name answered to no file, so every function listed on such a line went uncached, and the line itself was reported as an entry answering to nothing.

In the statistics package, whose INDEX puts several names on 70 of its 428 name lines, this hid 221 functions from the caches and produced 70 spurious findings.

Affects package_texi2cache, folder_texi2cache, classdef_texi2cache and function_texi2cache. The HTML and Qt help routes take their function lists from pkg describe, which uses Octave's own parser, and were never affected: documentation published with 0.8.0 or earlier is unaffected by this.

pkg-octave-doc-0.8.0

This release adds a third documentation route. Alongside the HTML pages and the Qt help file, a package can now regenerate its doc-cache files, which is what lookfor searches. The help texts themselves can also be checked without building anything at all.

Class members reach lookfor

Octave's doc_cache_create resolves each file by its bare name, so a classdef contributes a single entry and its methods and properties contribute none. They are invisible to lookfor and to everything built on it. Four new
functions write them in:

• package_texi2cache rebuilds every cache of a package, run at its root.
• folder_texi2cache rebuilds the cache of one directory.
• classdef_texi2cache writes a class and every member it documents.
• function_texi2cache writes a single function's entry.

The members cached are the ones classdef_texi2html publishes, so a class reads the same way online and in a search. This release ships a cache of its own built that way, so lookfor answers for every property and method of pkg_doc_options: 30 entries where Octave builds 14.

-auto limits the work to what git reports as changed, and -check reports what would change without writing, so a tree can be tested for a stale cache before a commit. A package's INDEX decides what is cached, and a name it does not list is skipped and reported. Where git is absent or the tree is not a repository, -auto is ignored with a warning and everything is rebuilt.

Help texts are checked

check_texi_docs reads the help texts of a tree and reports what is wrong with them, writing nothing at all. It runs from wherever it is called and works downwards, so a package root covers a package and inst covers what is below it. Nothing is rendered and no definition is loaded, so it is fast: a few seconds over a package.

It checks everything it finds, a Hidden member and a private helper included, which are the help texts nothing else looks at.

Twelve rules cover a @deftypefn header broken across lines, body text left on an @end line, a literal @ that is neither doubled nor a command, an unbalanced brace, an unclosed block, a category label naming neither the class nor the package, a public member with no help text, a source line wider than a package asks for, @seealso in the help of a class member, and three about INDEX. package_texi2qch now reports the first group as it builds, naming the member and the line.

Settings

The new pkg_doc_options class carries the location of a package's INDEX, how much a run prints, and the severity of each rule. Every property is public and documented, so the object is the list of what can be configured.

save_to_json writes back only the settings that differ from the defaults, and a file is read for whatever the running release understands, so one written for a later release is read in part rather than refused.
package_texi2cache and check_texi_docs read doc-options.json from a package root when one is there, so a package's own conventions are applied without being asked for; package_texi2qch takes the object through its 'Options' pair.

Fixes

• list_packages returned nothing usable from Octave Packages. A dependency is named there by a string carrying the package and any version it asks for, as in octave (>= 9.1.0), where the function read an object with a name field, and a release list decodes to a cell array whenever its entries carry different fields, where the function assumed a struct array. It now reads both forms and returns 139 of the 141 packages listed, and takes the index as an argument so a selection can be made from a copy taken earlier.

• A class declaring no methods at all can now be documented. classdef_texi2html raised rather than rendering such a class, so one carrying only properties has never had a page.

• A property inherited from a superclass is documented on the subclass page. Anything inherited was dropped without a warning, so a subclass adding no properties of its own published no properties block at all. In the statistics package this affected four pages. Rebuilding a package's documentation picks the properties up.

Upgrading

Nothing that existed before has changed shape. package_texi2qch takes one new optional 'Options' pair and every other signature is untouched.

README.md is no longer carried in the release tarball.

Packages whose documentation is rebuilt with this release pick up the inherited properties fix, and can ship a doc-cache carrying their class members by running package_texi2cache at their root.

pkg-octave-doc-0.7.7

Adds a landing page to the Qt help file a package ships, and closes four defects in what gets rendered.

• The contents tree opens on an overview. Double-clicking a package in the Documentation tab landed on whichever INDEX category happened to come first. package_texi2qch now generates a landing page and points the root of the tree at it, carrying the package name, version and description, and every documented name under its category against the first sentence of its help text.
• A @tex formula is rendered as its @ifnottex alternative, and dropped when the docstring carries none (issue #23). The Qt documentation browser runs no JavaScript, so the MathJax that typesets a formula in the online pages is not available to it and the TeX reached the reader as source. This is what help prints in the terminal for the same docstring.
• @math{...} is rendered as <em class="math">, the element makeinfo emits. A bare <math> is the MathML root element, so an HTML5 parser read everything after it as foreign content: an inline tag inside a formula, as @math{100 * (1 - @var{alpha})%} produces, closed the formula early and left the remainder of it outside. The Qt help browser was unaffected, rendering the content of an unknown tag as plain inline text.
• A class whose method is documented outside texinfo keeps its page. Such a method left classdef_texi2html without a first sentence or a body, raising 'mtds_fs' undefined for the first one in a class and repeating the previous method's documentation for any later one. It now renders as not documented.
• A summary no longer loses its first character when the docstring body starts at column 0, as an oct-file's does. It was read by counting a fixed offset past the paragraph tag, which is correct only for an indented body.

pkg-octave-doc-0.7.6

Adds package_texi2qch, which builds a package's Qt compressed help file so that the package's documentation appears in the Documentation tab of Octave's GUI.

• New function package_texi2qch. It writes <pkgname>.qch into the current working directory. pkg load registers doc/<pkgname>.qch from a package's installation directory and pkg unload unregisters it, so the generated file has to be placed there before the release tarball is built.
• A page per INDEX category, a page tree per classdef. Every function listed in the INDEX is rendered onto its category's page. Every classdef gets a page of its own carrying the class help text, a properties page and a methods page, nested under the category its INDEX entry puts it in.
• A grouped classdef takes one page per group. A class that sorts its methods under ** Group Name ** banners, as classdef_texi2html already reads them, gets a page per banner instead of a single methods page.
• Demos are excluded, code and figures alike. The result is 1.05 MB for statistics and 0.29 MB for datatypes.

pkg-octave-doc-0.7.5

• Demos are now found for functions inside a +namespace directory. They are retrieved through test, which locates a file with file_in_loadpath, and that does not resolve a namespaced name such as geom.offset; no error was raised, so a namespaced package was documented without any of its demos.
• Demo figure titles are no longer clipped. PNG figures were printed with their font size doubled along with the canvas, but -F is relative to the canvas, so the text came out at twice its nominal size and a long title ran past both edges of the frame; 43 of the 83 titled figures in one package build were affected. Figures are still printed at twice the nominal size, which was the point of the doubling.