Hi Kai, and everyone on this list,
I have a question that shares the title and advice of this on this old e-mail thread, specifically a)
a) Individual function documentation [4,5] generated from the
m-files help text (Texinfo) and demos ("generate_html"
package [9])
To document a local octave package I created. The package works fine to use pkg install, pkg load etc, and I can also use generate_html to generate a website with the documentation.
However, the generated documentation seems to use the old template from octave forge (I think dated to 2017 ish, based on a snapshot I found of the Octave Forge via the Internet Archive website). Is it possible to generate the documentation in the more modern interface Octave forge has? Looking at the source code of generate_html in the current version 0.3.2, I assume this is likely due to the code still referring to the old images:
Thank you,
On 10/2/20 3:53 AM, Chuck Cook wrote:
> On Thu, 2020-10-01 at 13:48 +0900, Kai Torben Ohlhus wrote:
>> On 9/30/20 9:20 PM, Chuck Cook wrote:
>>> I picked this link out of one of the other threads.
>>> https://github.com/gnu-octave/pkg-example
>>>
>>>
>>> My question is:
>>> How is new package documentation tied into the regular octave
>>> documentation? I see packages that obviously have had a lot of work put
>>> into them. But how to use them is cryptic and superficial.
>>>
>>> Chuck
>>
>>
>> Thank you for your interest. The "pkg-example" [1] is created according
>> to the only and official Octave package documentation in the manual [2].
>> Thus using "pkg-example" (also outside GitHub) you do not need to worry
>> to miss something important that Octave's "pkg" cannot install it properly.
>>
>> As an example it serves to demonstrate the bare necessary minimum. And
>> yes, developing "simple" Octave packages is astonishingly simple 😉
>>
>> Depending on your needs and package purpose, those packages can of
>> course increase (dramatically) in complexity, e.g. "bootstrap",
>> "configure.ac", ... But all this is not necessary for the start and
>> should best be avoided to reduce the maintenance burden current packages
>> are suffering from.
>>
>>> But how to use them is cryptic and superficial.
>>
>> What do you mean by this? Do you mean lack of package documentation?
>>
>> HTH,
>> Kai
>>
> I am referring to package documentation. I want to include brief
> examples, possibly a tiny bit of theory.
>
Sorry, I got your question wrong. To my knowledge there have been
attempts, but never there was a working and approved "standard" for
package documentation, as the Octave manual shows [2]:
> package/doc
> An optional directory containing documentation for the package.
> The files in this directory will be directly installed in a sub-
> directory of the installed package for future reference.
Every package maintainer does what he thinks is best. One prominent
example using all potential package documentation approaches (resulting
in unmaintained duplication) is the "interval" package [3]:
a) Individual function documentation [4,5] generated from the
m-files help text (Texinfo) and demos ("generate_html"
package [9])
b) some user manual with more theory [6] (Texinfo source in the
package "doc" directory [7], but generated and hosted manually,
never updated in two years, as the package itself)
c) Octave wiki [8]
My advise to you is:
(I) write the most documentation for each individual function with some
meaningful complete examples/demos. When a user has a problem, my
impression is that reading a lengthy manual is the last thing he would
do. For me unfortunately too, it goes mostly like "PROBLEM -> Try to
hack around -> help func -> Web search -> 10 minutes forums like
StackOverflow -> Search for manual -> Ask in some forum for help".
(II) write the bigger documentation in a format as simple as possible
(e.g. Markdown) which nicely renders math, tables via extensions and
offers via tools like pandoc almost unlimited export possibilities to
other markup languages (Texinfo, LaTeX, ...) and looks good
(automatically rendered) even in the source repository by default.
Texinfo is ugly and weird markup, do not start with it if you don't have
to 🙃
(III) host your bigger documentation at a location you can easily access
and update by yourself and just provide a link to it from all other
locations. Being dependent on some admin's time and grace to get an
update of your docs is very frustrating for a task no programmer likes
anyways 😇
(II) and (III) in short: use the Octave wiki [8].
Kai
[1] https://github.com/gnu-octave/pkg-example
[2] https://octave.org/doc/v5.2.0/Creating-Packages.html
[3] https://octave.sourceforge.io/interval/
[4] https://octave.sourceforge.io/interval/overview.html
[5] https://octave.sourceforge.io/interval/function/@infsup/plot.html
[6] https://octave.sourceforge.io/interval/package_doc/
[7] https://sourceforge.net/p/octave/interval/ci/default/tree/doc/
[8] https://wiki.octave.org/Interval_package
[9] https://octave.sourceforge.io/generate_html/
--