Quantcast

[OF] Docs, Demos and Test for External package

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

[OF] Docs, Demos and Test for External package

Juan Pablo Carbajal-2
Hi all,

I am setting up an external OF package

https://bitbucket.org/KaKiLa/gpml

the new Makefile runs flawlessly and I am able to install the package.
Now because this is package built form code meant for Matlab there are
several things that aren't present in the created package:
1. Documentation (I mean texinfo strings)
2. Demos
3. Tests

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"

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?

# Copyright
#
#

# Author:

# -*- texinfo -*-
# @defun {y =} tt(@var{x})
# A simple documentation of @command{tt} that takes the input @var{x}
# @end defun

function y = tt(x)
% Y = TT(X)
% A simple documentation of TT that takes the input X
y = x;
endfunction


Thanks

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Loading...