Development.rst

===========
Development
===========

Structure
=========

The sources for functions and classes are in ``src/``.  Private functions (mostly C++ source files
which are to be compiled into ``*.mex``) are implemented in
``private/maox_some_function.*``. (``maox`` stands for "mex file for CaosDB".

Writing Documentation
=====================

- The first string after the copyright block is used for documentation.  This implies that the
  copyright block must be recognized as such: A copyright line should be the first line there.
- Documentation should be written as TexInfo (see below for details) in order to be available in the
  online documentation.
- Extract documentation from file:
  ``[txt, form] = get_help_text_from_file(make_absolute_filename('pkg/inst/some_function.m'))``
- Generate HTML documentation from single file:

    .. code-block:: octave

       pkg uninstall caosdb
       pkg install caosdb.tar.gz
       pkg load caosdb
       html_help_text('some_function', './htdocs/some.html', 'octave-forge', pkgname="caosdb")
- Generate HTML documentation for a package:

    .. code-block:: octave

       generate_package_html('caosdb', 'htdocs', 'octave-forge')

TexInfo details
---------------

Here is an Example for texinfo documentation:..
  https://github.com/gnu-octave/octave/blob/default/scripts/geometry/inpolygon.m

Useful TexInfo commands:

- ``@deftypefn`` ::
    Define a function that can be called.  Example code:..
    ``@deftypefn{Function File} {@var{out} =} caosdb_exec (@var{arg})``