diff --git a/pkg/doc/development.md b/pkg/doc/development.md new file mode 100644 index 0000000000000000000000000000000000000000..566f8794649a67bbcf54707df358de5d8446468f --- /dev/null +++ b/pkg/doc/development.md @@ -0,0 +1,17 @@ +# How to write documentation # + +- Example for texinfo documentation: + https://github.com/gnu-octave/octave/blob/default/scripts/geometry/inpolygon.m +- 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: + ```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: + ```octave +generate_package_html('caosdb', 'htdocs', 'octave-forge') +``` diff --git a/pkg/inst/some_function.m b/pkg/inst/some_function.m index dcfaaac16d0b9942cc9b33632445b30dfb7a6b38..3b224dfec2a6a4305830810581807278177dcbea 100644 --- a/pkg/inst/some_function.m +++ b/pkg/inst/some_function.m @@ -1,5 +1,5 @@ -% (C) Copyright 2021 IndiScale GmbH <info@indiscale.com> -% (C) Copyright 2021 Daniel Hornung <d.hornung@indiscale.com> +% Copyright (C) 2021 IndiScale GmbH <info@indiscale.com> +% Copyright (C) 2021 Daniel Hornung <d.hornung@indiscale.com> % % This file is a part of the CaosDB Project. % @@ -16,6 +16,18 @@ % 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/>. +% -*- texinfo -*- +% @deftypefn {Function File} {@var{result} =} some_function (@var{arg1}, @var{arg2}) +% This is some function. +% +% For example, this function could be called like this: +% @example +% some_function (1, 2); +% @end example +% +% @seealso{some_function} +% @end deftypefn + function result = some_function(arg1, arg2) if arg1 >= arg2 error("arg1 must be smaller than arg2!"); diff --git a/pkg/utils/Make_Doc.m b/pkg/utils/Make_Doc.m new file mode 100644 index 0000000000000000000000000000000000000000..8a994300ef6583dfd6415aa5c2a8a90b628d223b --- /dev/null +++ b/pkg/utils/Make_Doc.m @@ -0,0 +1,31 @@ + +header = @(a_1, a_2, a_3) ... + sprintf([... + '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"\n', ... + ' "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">\n', ... + '<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">\n', ... + ' <head>\n', ... + ' <meta http-equiv="content-type" content="text/html; charset=utf-8" />\n', ... + ' <meta name="date" content="2021-07-09"/>\n', ... + ' <meta name="generator" content="generate_html 0.4.0" />\n', ... + ' <meta name="author" content="The Octave-Forge Community" />\n', ... + ' <meta name="description" content="Octave-Forge is a collection of packages ', ... + 'providing extra functionality for GNU Octave." />\n', ... + ' <meta name="keywords" lang="en" content="Octave-Forge, Octave, extra packages" />\n', ... + ' <title>The ''caosdb'' Package</title>\n', ... + ' <link rel="stylesheet" type="text/css" href="../octave-forge.css" />\n', ... + ' <script src="../fixed.js" type="text/javascript"></script>\n', ... + ' <script src="../javascript.js" type="text/javascript"></script>\n', ... + ' <script src="../footer.js" type="text/javascript"></script>\n', ... + ' <link rel="shortcut icon" href="../favicon.ico" />\n', ... + ' </head>\n', ... + ' <body onload="javascript:fix_top_menu ();">\n', ... + ' <script> write_docs_left_menu (''..''); </script>\n', ... + '<div id="doccontent">' ... +]) + +of_options = get_html_options("octave-forge"); +of_options.__header__ = header; +% (Re)loading caosdb package +pkg uninstall caosdb; pkg install caosdb.tar.gz; pkg load caosdb; +generate_package_html('caosdb', 'htdocs', of_options);