Re: [OF] Docs, Demos and Test for External package

[Oliver Heimlich]

On 17.02.2017 00:38, Juan Pablo Carbajal wrote:
> Hi all,
> 
> I am setting up an external OF package
> 
> https://bitbucket.org/KaKiLa/gpml

> several things that aren't present in the created package:
> 1. Documentation (I mean texinfo strings)
> 2. Demos
> 3. Tests

You maintain a (downstream) Octave port of the original (Matlab only)
package and want to be able to receive new version from upstream, right?

> This prevents a nice html help automatically generated and 'make
> check' is useless.
> 
> How would you suggest I include these missing things?
> 
> a. For demos and test I could create extra files with the demo/test
> code and concatenate them at packaging time. E.g. "covSEiso.m" would
> have test and demos in "octave_pkg/covSEiso.otd" (a plan text file)
> and at packaging time I would do "cat octave_pkg/covSEiso.otd >>
> $(RELEASE_DIR)/inst/cov/covSEiso.m"

You can add separate test files under the name FUNCTIONNAME.tst.

Demos should go into the original function file if possible, such that
“demo FUNCTIONNAME” works out of the box.  It should be possible to
append these lines in your codebase and merge new upstream versions
without problems using your version control system (i. e. use an
upstream branch). You could also do this with test code. Demo and test
code should simply be ignored by Matlab.

> b. I am a little blocked with the docstrings. The problem is that the
> functions already have documentation. I could nevertheless make a
> Octave-style copyright and documentation and insert it above the
> current function definition. This seems to work alright in the
> following dummy example, but duplicates the content of the file. What
> do you think?

I would not want to duplicate the documentation. Maybe there is a tool
to automatically prettify the plain text documentation. This could be
used by generate_html for all non-texinfo documentation.

Oliver