From 851799b9c6a7ca4112e641036ebdbd8b735f77e1 Mon Sep 17 00:00:00 2001
From: marcodeltufo <marco.deltufo@exact-lab.it>
Date: Thu, 6 Jul 2023 17:47:29 +0200
Subject: [PATCH] .
---
.../apis/java-javascript-v3-api.md | 3 +--
.../apis/matlab-v3-api.md | 2 +-
.../apis/personal-access-tokens.md | 21 +++++++++----------
.../apis/python-v3-api.md | 4 ++--
4 files changed, 14 insertions(+), 16 deletions(-)
diff --git a/docs/software-developer-documentation/apis/java-javascript-v3-api.md b/docs/software-developer-documentation/apis/java-javascript-v3-api.md
index 8a99609d0bc..132d3e70907 100644
--- a/docs/software-developer-documentation/apis/java-javascript-v3-api.md
+++ b/docs/software-developer-documentation/apis/java-javascript-v3-api.md
@@ -1,5 +1,4 @@
-Java/Javascript openBIS V3 API
-==============================
+# Java / Javascript (V3 API) - openBIS V3 API
## I. Architecture
diff --git a/docs/software-developer-documentation/apis/matlab-v3-api.md b/docs/software-developer-documentation/apis/matlab-v3-api.md
index b9760c0cbbb..1b73f1381fc 100644
--- a/docs/software-developer-documentation/apis/matlab-v3-api.md
+++ b/docs/software-developer-documentation/apis/matlab-v3-api.md
@@ -1,4 +1,4 @@
-# How to access openBIS from MATLAB
+# Matlab (V3 API) - How to access openBIS from MATLAB
## Preamble
[openBIS](https://wiki-bsse.ethz.ch/display/bis/Home) is a research data management system developed by [ETH SIS](https://sis.id.ethz.ch/). Data stored in openBIS can be accessed directly via the web UI or programmatically using APIs. For example, [pyBIS](https://sissource.ethz.ch/sispub/openbis/tree/master/pybis) is a project that provides a Python 3 module for interacting with openBIS.
diff --git a/docs/software-developer-documentation/apis/personal-access-tokens.md b/docs/software-developer-documentation/apis/personal-access-tokens.md
index 8bed1565929..f4668de5741 100644
--- a/docs/software-developer-documentation/apis/personal-access-tokens.md
+++ b/docs/software-developer-documentation/apis/personal-access-tokens.md
@@ -1,7 +1,6 @@
-Personal Access Tokens
-======================
+# Personal Access Tokens
-#### Background
+## Background
"Personal access token" (in short: PAT) is an openBIS feature that was
introduced to simplify integration of openBIS with other systems. Such
@@ -33,7 +32,7 @@ Depending on a use case and a type of the integration that could cause
smaller or bigger headaches for the developers of the external system.
Fortunately, "Personal access tokens" come to a rescue.
-#### What are "Personal access tokens" ?
+## What are "Personal access tokens" ?
A personal access token (in short: PAT) is very similar to a session
token but there are also some important differences.
@@ -67,12 +66,12 @@ Differences:
transition period from one soon to be expired PAT to a new PAT that
replaces it without losing the session's state
-#### Who can create a "Personal access token" ?
+## Who can create a "Personal access token" ?
Any openBIS user can manage its own PATs. Instance admin users can
manage all PATs in the system.
-#### Where can I use "Personal access tokens" ?
+## Where can I use "Personal access tokens" ?
Endpoints that support PATs:
@@ -99,7 +98,7 @@ DSS:
- Session Workspace Provider
- SFTP
-#### Where "Personal access tokens" are stored ?
+## Where "Personal access tokens" are stored ?
PATs are stored in "personal-access-tokens.json" JSON file. By default
the file is located in the main openBIS folder where it survives openBIS
@@ -109,7 +108,7 @@ The location can be changed using "personal-access-tokens-file-path"
property in AS service.properties. The JSON file is read at the openBIS
start up.
-#### How long should my "Personal Access Tokens" be valid ?
+## How long should my "Personal Access Tokens" be valid ?
Because of security reasons PATs should not be valid indefinitely.
Instead, each PAT should have a well defined validity period after which
@@ -128,7 +127,7 @@ under the hood to the same openBIS session. Therefore, even if one of
such PATs expires the session is kept active and its state is
maintained.
-#### Configuration
+## Configuration
"Personal access tokens" functionality is enabled by default. To
configure it please use AS service.properties:
@@ -145,7 +144,7 @@ configure it please use AS service.properties:
# set validity warning period (in seconds) - owners of personal access tokens that are going to expire within this warning period are going to receive email notifications (default: 5 days)
personal-access-tokens-validity-warning-period = 259200
-#### Typical Application Workflow
+## Typical Application Workflow
Most typical use case for Personal Access Tokens is to run code on a
third party service against openBIS.
@@ -275,7 +274,7 @@ management.
}
-#### V3 APIÂ
+## V3 APIÂ
Code examples for personal access tokens can be found in the main V3 API
documentation: [openBIS V3
diff --git a/docs/software-developer-documentation/apis/python-v3-api.md b/docs/software-developer-documentation/apis/python-v3-api.md
index 20ba1f6a2f7..ade85dd322e 100644
--- a/docs/software-developer-documentation/apis/python-v3-api.md
+++ b/docs/software-developer-documentation/apis/python-v3-api.md
@@ -1,4 +1,4 @@
-# Welcome to pyBIS!
+# Python (V3 API) - Welcome to pyBIS!
pyBIS is a Python module for interacting with openBIS. pyBIS is designed to be most useful in a [Jupyter Notebook](https://jupyter.org) or IPython environment, especially if you are developing Python scripts for automatisation. Jupyter Notebooks offer some sort of IDE for openBIS, supporting TAB completition and immediate data checks, making the life of a researcher hopefully easier.
@@ -24,7 +24,7 @@ pip install jupyter
pip install jupyterlab
```
-# General Usage
+## General Usage
### TAB completition and other hints in Jupyter / IPython
--
GitLab