diff --git a/.docker/Dockerfile b/.docker/Dockerfile index 319682d386d571f706290ca4083efd017849e699..c6e60fa4326da8de45e387154a81b76548cad46b 100644 --- a/.docker/Dockerfile +++ b/.docker/Dockerfile @@ -8,3 +8,5 @@ RUN apt-get update \ python3-sphinx RUN pip3 install breathe miss_hit sphinx-rtd-theme recommonmark +RUN wget -O generate_doc_unreleased.zip https://github.com/gnu-octave/generate_doc/archive/refs/heads/main.zip +RUN octave --eval "pkg install generate_doc_unreleased.zip" diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 164ac33b41939514ce25f13af311e7ce3d54bd4d..ad6495c3de4accd0e5afeeb68981a1cb31022687 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -46,9 +46,8 @@ build-testenv: stage: setup image: docker:20.10 only: - - main - schedules - - f-pipeline + - f-package-docs script: - cd .docker - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY diff --git a/src/doc/Gen_HTML.m b/src/doc/Gen_HTML.m new file mode 100644 index 0000000000000000000000000000000000000000..062322ddccd86444869717c95c0b54502275cfe4 --- /dev/null +++ b/src/doc/Gen_HTML.m @@ -0,0 +1,23 @@ +% (C) Copyright 2021 IndiScale GmbH <info@indiscale.com> +% (C) Copyright 2021 Daniel Hornung <d.hornung@indiscale.com> +% +% This file is a part of the CaosDB Project. +% +% 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/>. + +% ------------------------------------------------------------------------ +% Build the HTML documentation. + +pkg load generate_doc +generate_package_html("caosdb", "_build_octave/") diff --git a/src/doc/Makefile b/src/doc/Makefile new file mode 100644 index 0000000000000000000000000000000000000000..37fe74074cf2f4f8db2f2af3bc78a506c09eb175 --- /dev/null +++ b/src/doc/Makefile @@ -0,0 +1,51 @@ +# ** header v3.0 +# 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> +# +# 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/>. +# +# ** end header + +# This Makefile is a wrapper for sphinx scripts. +# +# Code documentation of the Octave code is created by `generate_doc` from +# https://github.com/gnu-octave/generate_doc, Sphinx adds in additional documents. + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= -a +SPHINXBUILD ?= sphinx-build +OCTAVE ?= octave +OCTAVEBUILDDIR = _build_octave +PY_BASEDIR = ../caosdb +SOURCEDIR = . +BUILDDIR = ../../build/doc + + +.PHONY: doc-help Makefile + +# Put it first so that "make" without argument is like "make help". +doc-help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile octavedoc + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +octavedoc: + mkdir -p $(OCTAVEBUILDDIR) + @$(OCTAVE) Gen_HTML.m diff --git a/src/doc/conf.py b/src/doc/conf.py new file mode 100644 index 0000000000000000000000000000000000000000..fe13ebe081fc4c924103dededc76085738e7f384 --- /dev/null +++ b/src/doc/conf.py @@ -0,0 +1,128 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('../caosdb')) + + +import sphinx_rtd_theme + + +# -- Project information ----------------------------------------------------- + +project = 'OctaveCaosDB' +copyright = '2021, IndiScale GmbH' +author = 'Daniel Hornung' + +# The short X.Y version +version = '0.1' +# The full version, including alpha/beta/rc tags +#release = '0.5.2-rc2' +release = '0.1.0' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autosectionlabel', + 'sphinx.ext.intersphinx', + 'sphinx.ext.napoleon', # For Google style docstrings + "recommonmark", # For markdown files. + "sphinx_rtd_theme", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +source_suffix = ['.rst', '.md'] + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# + +html_theme = "sphinx_rtd_theme" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = [ + '_static', + '_build_octave', +] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'caosdb-octavelibdoc' + + +# -- Extension configuration ------------------------------------------------- + +# -- Options for intersphinx ------------------------------------------------- + +# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_mapping +intersphinx_mapping = { + "python": ("https://docs.python.org/", None), + "caosdb-mysqlbackend": ("https://caosdb.gitlab.io/caosdb-mysqlbackend/", + None), + "caosdb-server": ("https://caosdb.gitlab.io/caosdb-server/", None), +} diff --git a/src/doc/index.rst b/src/doc/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..bd29c6c56acf5c173e94ae6471a6aeba56ea4b93 --- /dev/null +++ b/src/doc/index.rst @@ -0,0 +1,28 @@ + +Welcome to PyCaosDB's documentation! +==================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + :hidden: + + Getting started <README_SETUP> + tutorials/index + Concepts <concepts> + Configuration <configuration> + Administration <administration> + API documentation<_apidoc/caosdb> + +This is the documentation for the Python client library for CaosDB, ``PyCaosDB``. + +This documentation helps you to :doc:`get started<README_SETUP>`, explains the most important +:doc:`concepts<concepts>` and offers a range of :doc:`tutorials<tutorials/index>`. + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search`