diff --git a/CHANGELOG.md b/CHANGELOG.md index 7ba0d8c13f4375ccd27d81b8c8733eab0edba42f..fd2bbfd27503488cbb7b2e7aef30ff959f3f323d 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 290350105740a206ac47cb5bd761a3c6655b2c15..896ee67ed03a493379c182ef617f0654a18f3ae4 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 cb97bc992169a2b9f38d802b0587b3a630cdef1b..5458c5300efc82e55686bc1cd6934182c5c8e39a 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 0000000000000000000000000000000000000000..23e5fc4f6ddb666757fb9c79e192e07ffed8fb44 --- /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 9e89cf68cf31c4b75d4b8c8342e1ce723b5b8e13..eecfa112cfa20121b2c901389f1bcbe2ac7a3c8c 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 0000000000000000000000000000000000000000..6805181e73a7f338fbacb74bdd9f734360404372 --- /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 07b49267571f3f8dcf2ff259c3b6184f9279f6ce..c95559d92b344a08bf33f9398789174fb00742b2 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 7d2129834b618b45381121ad0391c9ff213421e0..8b3190845b3f288872d159e32a89e7216639cc94 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 .