WIP DOC: Documentation system.

DESCRIPTION

@@ -6,6 +6,8 @@ Author: Daniel Hornung <d.hornung@indiscale.com>
 Maintainer: Daniel Hornung <d.hornung@indiscale.com>
 Title: Octave and Matlab library for CaosDB
 Description: This package contains utility functions to interact with CaosDB.
+ <p>It makes use of <a href=https://gitlab.com/caosdb/caosdb-cpplib>libcaosdb</a>
+ which must be installed on the system.</p>
 License: AGPLv3
 Categories: data management
 Url: https://gitlab.com/caosdb/caosdb-octavelib

Makefile

@@ -31,7 +31,7 @@ help:
 
 .PHONY: doc
 doc:
-	cd doc && $(MAKE) html
+	$(MAKE) -C doc html
 
 ###############################################################################
 #                                   Styling                                   #
@@ -121,3 +121,14 @@ dist/caosdb.tar.gz: dist/
 .PHONY: dist/
 dist/:
 	mkdir -p dist
+
+###############################################################################
+#                                   Cleaning                                  #
+###############################################################################
+
+clean: doc_clean
+.PHONY: clean
+
+doc_clean:
+	rm -r doc/_build_octave/ build/doc/
+.PHONY: doc_clean

doc/Development.rst

@@ -32,6 +32,19 @@ Writing Documentation
 
        generate_package_html('caosdb', 'htdocs', 'octave-forge')
 
+Requirements
+------------
+
+
+- We use a dedicated Octave package for documentation generation: ` ``generate_html`` <https://keepachangelog.org>`_.  This package
+  can be installed as follows:
+
+    .. code-block:: octave
+
+        pkg install "https://downloads.sourceforge.net/project/octave/Octave%20Forge%20Packages/Individual%20Package%20Releases/generate_html-0.3.2.tar.gz"
+
+.. _generate_html: https://gnu-octave.github.io/packages/generate_html
+
 TexInfo details
 ---------------
 

doc/Generate_Octave_Doc.m

@@ -42,9 +42,11 @@ header = @(a_1, a_2, a_3) ...
            '<div id="doccontent">' ...
           ]);
 
-pkg load generate_doc;
+pkg load generate_html;
 of_options = get_html_options("octave-forge");
 setfield(of_options, '__header__', header);
+of_options.package_doc = "caosdb.texi";
+
 % (Re)loading caosdb package
 pkg install ..;
 pkg load caosdb;

doc/Makefile

@@ -42,7 +42,7 @@ doc-help:
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
+%: Makefile octavedoc
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 octavedoc:

doc/caosdb.texi

+@c This file is a part of the CaosDB Project.
+@c
+@c Copyright (C) 2021 IndiScale GmbH <info@indiscale.com>
+@c Copyright (C) 2021 Daniel Hornung <d.hornung@indiscale.com>
+@c
+@c This program is free software: you can redistribute it and/or modify
+@c it under the terms of the GNU Affero General Public License as
+@c published by the Free Software Foundation, either version 3 of the
+@c License, or (at your option) any later version.
+@c
+@c This program is distributed in the hope that it will be useful,
+@c but WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+@c GNU Affero General Public License for more details.
+@c
+@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
+@top CaosDB library for Octave/Matlab
+
+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.
+
+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}.
+
+@deftypefn {Class} {} Caosdb ()
+This is the main class of the CaosDB client for Octave.
+
+Print usage help and return:
+@example
+caosdb --help;
+@end example
+
+Print the version and return:
+@example
+caosdb --version;
+@end example
+
+Test the default connection, print the server's version and return.
+@example
+caosdb --test-connection;
+@end example
+
+@end deftypefn
+

src/configure

@@ -22,6 +22,6 @@ mkdir -p $BUILD_DIR
 pushd $BUILD_DIR
 
 conan install .. -s "compiler.libcxx=libstdc++11"
-cmake ..
+cmake .. -D LINTING=OFF -D AUTOFORMATTING=OFF
 
 popd