Merge branch 'sphinx-docs' into 'master'

Sphinx docs

See merge request giscience/big-data/ohsome/ohsome-api!43

Jenkinsfile

@@ -133,6 +133,47 @@ pipeline {
       }
     }
 
+    // START CUSTOM ohsome API
+    stage ('Publish API Docs') {
+      when {
+        expression {
+          return env.BRANCH_NAME ==~ /(^[0-9]+$)|(^(([0-9]+)(\.))+([0-9]+)?$)|(^master$)/
+        }
+      }
+      steps {
+        script {
+          DOC_RELEASE_REGEX = /^([0-9]+(\.[0-9]+)*)$/
+          DOCS_DEPLOYMENT = "development"
+          API_DOCS_PATH = "development"
+          if(VERSION ==~ DOC_RELEASE_REGEX) {
+            DOCS_DEPLOYMENT = "release"
+            API_DOCS_PATH = sh(returnStdout: true, script: 'cd docs && python3 get_pom_metadata.py | awk \'/^Path:/{ print $2 }\'').trim()
+          }
+
+          publish_dir="/srv/javadoc/" + reponame + "/" + API_DOCS_PATH + "/"
+          venv_name='venv-ohsome-api-apidocs'
+
+          if (!fileExists("$venv_name")) {
+            sh "python3 -m venv $venv_name"
+          }
+
+          sh """
+            source $venv_name/bin/activate
+            cd docs
+            pip install -r requirements.txt
+            DOCS_DEPLOYMENT=${DOCS_DEPLOYMENT} make clean html
+          """
+          sh "mkdir -p $publish_dir && rm -rf $publish_dir* && cp -r docs/_build/html/* $publish_dir"
+        }
+      }
+      post {
+        failure {
+          rocketSend channel: 'jenkinsohsome', message: "Deployment of api docs $reponame-build nr. ${env.BUILD_NUMBER} *failed* on Branch - ${env.BRANCH_NAME}  (<${env.BUILD_URL}|Open Build in Jenkins>). Latest commit from  ${author}." , rawMessage: true
+        }
+      }
+    }
+    // END CUSTOM ohsome API
+
     stage ('Reports and Statistics') {
       steps {
         script {

README.md

@@ -152,11 +152,41 @@ http://localhost:8080/elements/count/groupBy/boundary?bpolys={"type":"FeatureCol
 }
 ```
 
+## Documentation
+
+[Install Sphinx](https://www.sphinx-doc.org/en/master/usage/installation.html) before running the following commands e.g. by using this commands:
+```bash
+cd docs
+pip3 install -r requirements.txt
+```
+
+To update the ohsome API swagger files for the documentation:
+```bash
+cd docs
+wget 'https://api.ohsome.org/v1/docs?group=Data%20Aggregation' -O _static/swagger-aggregation.json
+wget 'https://api.ohsome.org/v1/docs?group=Data%20Extraction' -O _static/swagger-extraction.json
+wget 'https://api.ohsome.org/v1/docs?group=Metadata' -O _static/swagger-metadata.json
+```
+
+The documentation can be built with the following command:
+```bash
+cd docs
+make clean # if you want to recreate all pages
+make html
+```
+
+If you want to see the release version of the ohsome API docs, use this environment variable:
+```bash
+cd docs
+DOCS_DEPLOYMENT=release make clean html
+```
+
 ## Built With
 
 * [Eclipse](http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/oxygen1a) - IDE
 * [Spring Boot](https://projects.spring.io/spring-boot/) - Web framework
 * [Maven](https://maven.apache.org/) - Dependency management and project building
+* [Sphinx](https://www.sphinx-doc.org) - API documentation
 
 ## Tested With
 

docs/.gitignore

@@ -0,0 +1,2 @@
+_build
+__pycache__

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)