WIP DOC: Documentation

Makefile

@@ -130,5 +130,5 @@ clean: doc_clean
 .PHONY: clean
 
 doc_clean:
-	rm -r doc/_build_octave/ build/doc/
+	rm -r doc/_build_octave/ build/doc/ NEWS
 .PHONY: doc_clean

doc/Generate_Octave_Doc.m

@@ -47,7 +47,7 @@ of_options = get_html_options("octave-forge");
 setfield(of_options, '__header__', header);
 of_options.package_doc = "caosdb.texi";
 
-% (Re)loading caosdb package
+% (re)loading caosdb package
 pkg install ..;
 pkg load caosdb;
 generate_package_html('caosdb', '_build_octave/', of_options);

doc/Makefile

@@ -47,5 +47,7 @@ doc-help:
 
 octavedoc:
 	mkdir -p $(OCTAVEBUILDDIR)
+	# pandoc ../CHANGELOG.md -o ../NEWS
+	cp ../CHANGELOG.md ../NEWS
 	@$(OCTAVE) Generate_Octave_Doc.m
-
+	cp "_build_octave/caosdb/package_doc/Overview.html" "_build_octave/caosdb/overview.html"

doc/api/_caosdb.rst

-..
-    #
-    # This file is a part of the CaosDB Project.
-    #
-    # Copyright (C) 2021 Timm Fitschen <t.fitschen@indiscale.com>
-    # Copyright (C) 2021 IndiScale GmbH <info@indiscale.com>
-    #
-    # This program is free software: you can redistribute it and/or modify
-    # it under the terms of the GNU Affero General Public License as
-    # published by the Free Software Foundation, either version 3 of the
-    # License, or (at your option) any later version.
-    #
-    # This program is distributed in the hope that it will be useful,
-    # but WITHOUT ANY WARRANTY; without even the implied warranty of
-    # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    # GNU Affero General Public License for more details.
-    #
-    # You should have received a copy of the GNU Affero General Public License
-    # along with this program. If not, see <https://www.gnu.org/licenses/>.
-    #
-
-.. _coasdb:
-
-caosdb
-======
-
-
-.. toctree::
-    :glob:
-
-    function/*
-
-.. raw:: html
-   :file: ../_build_octave/caosdb/overview.html

doc/caosdb.texi

@@ -16,24 +16,142 @@
 @c You should have received a copy of the GNU Affero General Public License
 @c along with this program. If not, see <https://www.gnu.org/licenses/>.
 
-@node top
+@node Top
 @top CaosDB library for Octave/Matlab
 
-This package contains utility functions to interact with CaosDB, the
-flexible semantic data management platform.
+This package contains utility functions to interact with CaosDB, the flexible semantic data
+management platform.
 
-It makes use of @url{https://gitlab.com/caosdb/caosdb-cpplib, libcaosdb}
-which must be installed on the system.
+It makes use of @url{https://gitlab.com/caosdb/caosdb-cpplib, libcaosdb} which must be installed on
+the system.
 
-Full documentation how to install this package and a short tutorial for
-first steps with the Octave CaosDB library can be found on
-@url{https://docs.indiscale.com/caosdb-octavelib}, the source code for
-this library is freely available at
-@url{https://gitlab.com/caosdb/caosdb-octavelib}.
+Full documentation how to install this package and a short tutorial for first steps with the Octave
+CaosDB library can be found on @url{https://docs.indiscale.com/caosdb-octavelib}, the source code
+for this library is freely available at @url{https://gitlab.com/caosdb/caosdb-octavelib}.
+
+If you are interested in the documentation of the functions and classes provided by this library,
+follow this link to the @url{../overview.html, API overview}.
+
+@menu
+* Overview::  How CaosDB works in Octave, and first steps.
+* CaosDB::    The CaosDB class.  This class handles connections to CaosDB servers and transactions.
+* Index::     Complete index.
+@end menu
+
+@node Overview
+
+@chapter Overview
+@cindex Installation
+@section Installation
+
+@cindex Requirements for installation
+Before installing the @code{caosdb} library in Octave, you first need to install @i{libcaosdb} with
+Conan.  Typically, it should be sufficient to download the sources from
+@url{https://gitlab.com/caosdb/caosdb-cpplib} and execute @code{make conan}.
+
+@cindex Installation, with @code{pkg install}
+@unnumberedsubsec With @code{pkg install}
+Then get the Octave package for the @code{caosdb} library or its source code and install it from
+within Octave with @code{pkg install caosdb.tar.gz;} (if you downloaded the package) or @code{pkg
+install /path/to/source/dir;}.  To make the library contents available to your code, activate it
+with @code{pkg load caosdb;}
+
+@cindex Installation, manual
+@unnumberedsubsec Manual installation
+For other environments which lack a package management system, such as Matlab, you can go into the
+@code{src/} directory and call @command{./configure} there, followed by @command{make install}.  You
+will then have to copy the resulting files to a place which is in your search path so that the
+@file{.m} and @file{.mex} files can be found.  Once the files are in your search path, they are
+immediately available to your code.
+
+@cindex Configuration (libcaosdb)
+@unnumberedsubsec Configuration
+Since the Octave CaosDB library uses @i{libcaosdb}, the configuration is handled by libcaosdb as
+well.  In practice this means that there should be a configuration file, either in the current
+directory, your home directory or at a location specified by the @env{CAOSDB_CLIENT_CONFIGURATION}
+environment variable.  More information about the configuration is available at the
+@url{https://docs.indiscale.com/caosdb-cpplib, libcaosdb documentation}.
+
+@cindex First steps
+@section First steps
+
+Starting off with CaosDB in Octave is easy:
+
+@example
+%% Set up the library
+pkg load caosdb;   % Not necessary if you manually put the CaosDB files into your search path.
+c = Caosdb();      % Uses the default connection as defined in the configuration.
+c.info()           % Output some diagnostic message.
+
+%% Execute a simple query
+my_query = 'FIND Record MusicalInstrument WITH price > 2000';
+results = c.query(my_query);
+disp(['Found ' num2str(numel(results)) ' results']);
+if numel(results) > 0
+  disp(results@{1@});
+end
+@end example
+
+You can create and modify CaosDB entities much in the same way as with libcaosdb, so please refer to
+the documentation available there for details.  These operations, and also inserting, updating and
+deleting entities are straight-forward in Octave:
+
+@example
+%% Continuing from the code above...
+my_instrument = Entity();       % Create new entity, set role and name
+my_instrument.role = 'RECORD';
+my_instrument.name = 'My new theremin';
+
+% set parent
+instrument_id = c.query('FIND RecordType MusicalInstrument')@{1@}.id;
+instrument = Parent();
+instrument.id = instrument_id;
+
+my_instrument.set_parents(@{instrument@});
+
+% set property
+price_id = c.query('FIND Property price')@{1@}.id;
+price = Property();
+price.id = price_id;
+price.set_datatype('DOUBLE');   % Datatype must be set in order to set a value.
+price.value = 2300;             % Integer values would need to be cast to int64.
+
+my_instrument.set_properties(@{price@});
+
+%% Insert the instrument Record.
+insert_result = c.insert(@{my_instrument@});
+
+disp(insert_result@{1@}.id);
+
+@end example
+
+
+@section Further reading
+
+For more information, you may want to read up on
+@itemize
+@item The @code{Caosdb} class, which holds connection information and handles the transactions.
+@item The @code{Entity} class, a representation of CaosDB entities (Records, ReocrdTypes, Properties).
+@item The subordinate classes @code{Property} and @code{Parent}, used for adding information to
+      Entities.
+@end itemize
+
+@node CaosDB
+@comment  node-name,  next,  previous,  up
+@cindex CaosDB (class)
+@chapter The CaosDB class
+
+The CaosDB class holds information about the connection to a CaosDB server.  It provides a
+convenient interface to the possible transactions (insert, query, retrieve, update, delete) with the
+server.
+
+@enumerate
+@item
+This is the first item.
+@item
+This is the second item.
+@end enumerate
 
-If you are interested in the documentation of the functions and classes
-provided by this library, follow this link to the @url{../overview.html,
-API overview}.
 
 @deftypefn {Class} {} Caosdb ()
 This is the main class of the CaosDB client for Octave.
@@ -55,3 +173,7 @@ caosdb --test-connection;
 
 @end deftypefn
 
+
+@node Index
+@unnumbered Index
+@printindex cp

src/Caosdb.m

-% This file is a part of the CaosDB Project.
-%
 % Copyright (C) 2021 IndiScale GmbH <info@indiscale.com>
 % Copyright (C) 2021 Daniel Hornung <d.hornung@indiscale.com>
 %
@@ -16,6 +14,9 @@
 % You should have received a copy of the GNU Affero General Public License
 % along with this program. If not, see <https://www.gnu.org/licenses/>.
 
+%% Developer's note: Documentation may start to work with Octave 6, earlier versions cannot handle
+% the help strings in classdef files.
+
 % -*- texinfo -*-
 % @deftypefn {Class} {} Caosdb ()
 % This is the main class of the CaosDB client for Octave.
@@ -37,9 +38,6 @@
 %
 % @end deftypefn
 
-%!demo
-%! ## Print Help:
-%! caosdb --help;
 classdef Caosdb < handle
   properties
     connection = ""             % Will use the default connection