DOC: Basic structure for manual documentation.

Also amended Changelog and Readme.

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Versioning support (experimental). The version db.Version class can
   represents particular entity versions and also the complete history of an
   entity.
+* Automated documentation builds: `make doc`
 
 ### Changed ###
 

README_SETUP.md

@@ -9,3 +9,13 @@ tox
 # Code Formatting
 
 autopep8 -i -r ./
+
+# Documentation #
+
+Build documentation in `build/` with `make doc`.
+
+## Requirements ##
+
+- sphinx
+- sphinx-autoapi
+- recommonmark

src/doc/Makefile

@@ -25,7 +25,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -a
 SPHINXBUILD   ?= sphinx-build
 SPHINXAPIDOC   ?= sphinx-apidoc
 PY_BASEDIR    = ../caosdb

src/doc/concepts.rst

+========================
+The concepts of pycaosdb
+========================
+
+Some text...
+

src/doc/conf.py

@@ -42,6 +42,7 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',     # For Google style docstrings
+    "recommonmark",            # For markdown files.
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -51,7 +52,7 @@ templates_path = ['_templates']
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+# source_suffix = '.rst'
 
 # The master toctree document.
 master_doc = 'index'

src/doc/getting_started.md

+# Getting started with pycaosdb #
+
+1. Install
+2. import
+3. enjoy

src/doc/index.rst

@@ -5,6 +5,17 @@ Welcome to caosdb-pylib's documentation!
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
+   :hidden:
+
+   Getting started <getting_started>
+   Concepts <concepts>
+   tutorials
+   API documentation<_apidoc/modules>
+
+Welcome to the Python client library for CaosDB, ``pycaosdb``!
+
+This documentation helps you to :doc:`get started<getting_started>`, explains the most important
+:doc:`concepts<concepts>` and offers a range of :doc:`tutorials<tutorials>`.
 
 
 Indices and tables

unittests/docker/Dockerfile

@@ -3,7 +3,7 @@ RUN apt-get update && \
     apt-get install -y \
       pylint3 python3-pip tox git \
       curl pycodestyle \
-      python3-sphinx
+      python3-sphinx python3-recommonmark
 ARG COMMIT="dev"
 RUN git clone -b dev https://gitlab.com/caosdb/caosdb-pylib.git && \
     cd caosdb-pylib && git checkout $COMMIT && pip3 install .