From d205524f04f60e18444f1a69fcf5d9bd319e6050 Mon Sep 17 00:00:00 2001
From: Daniel <daniel@harvey>
Date: Thu, 3 Dec 2020 15:53:13 +0100
Subject: [PATCH] DOC: Basic structure for manual documentation.
Also amended Changelog and Readme.
---
CHANGELOG.md | 1 +
README_SETUP.md | 10 ++++++++++
src/doc/Makefile | 2 +-
src/doc/concepts.rst | 6 ++++++
src/doc/conf.py | 3 ++-
src/doc/getting_started.md | 5 +++++
src/doc/index.rst | 11 +++++++++++
unittests/docker/Dockerfile | 2 +-
8 files changed, 37 insertions(+), 3 deletions(-)
create mode 100644 src/doc/concepts.rst
create mode 100644 src/doc/getting_started.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7ba0d8c1..fd2bbfd2 100644
--- a/CHANGELOG.md
+++ b/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 ###
diff --git a/README_SETUP.md b/README_SETUP.md
index 29035010..896ee67e 100644
--- a/README_SETUP.md
+++ b/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
diff --git a/src/doc/Makefile b/src/doc/Makefile
index cb97bc99..5458c530 100644
--- a/src/doc/Makefile
+++ b/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
diff --git a/src/doc/concepts.rst b/src/doc/concepts.rst
new file mode 100644
index 00000000..23e5fc4f
--- /dev/null
+++ b/src/doc/concepts.rst
@@ -0,0 +1,6 @@
+========================
+The concepts of pycaosdb
+========================
+
+Some text...
+
diff --git a/src/doc/conf.py b/src/doc/conf.py
index 9e89cf68..eecfa112 100644
--- a/src/doc/conf.py
+++ b/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'
diff --git a/src/doc/getting_started.md b/src/doc/getting_started.md
new file mode 100644
index 00000000..6805181e
--- /dev/null
+++ b/src/doc/getting_started.md
@@ -0,0 +1,5 @@
+# Getting started with pycaosdb #
+
+1. Install
+2. import
+3. enjoy
diff --git a/src/doc/index.rst b/src/doc/index.rst
index 07b49267..c95559d9 100644
--- a/src/doc/index.rst
+++ b/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
diff --git a/unittests/docker/Dockerfile b/unittests/docker/Dockerfile
index 7d212983..8b319084 100644
--- a/unittests/docker/Dockerfile
+++ b/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 .
--
GitLab