From 866e4131c55da81e8f3d859c67956b301e4aa04b Mon Sep 17 00:00:00 2001
From: jpizarro <jose.pizarro-blanco@bam.de>
Date: Tue, 28 Jan 2025 15:09:55 +0100
Subject: [PATCH] Added tutorial and clean up docu structure

---
 docs/howtos/pybis/collections.md    |  3 --
 docs/howtos/pybis/datasets.md       |  3 --
 docs/howtos/pybis/objects.md        |  3 --
 docs/howtos/pybis/objects_props.md  |  3 --
 docs/howtos/pybis/parent_child.md   |  3 --
 docs/howtos/pybis/projects.md       |  3 --
 docs/howtos/pybis/searches.md       |  3 --
 docs/howtos/pybis/setup.md          |  3 --
 docs/howtos/pybis/spaces.md         |  3 --
 docs/index.md                       | 14 +++---
 docs/stylesheets/extra.css          | 27 ++++++++---
 docs/tutorials/create-masterdata.md |  3 --
 docs/tutorials/pybis.md             |  3 --
 docs/tutorials/tutorial.md          | 75 +++++++++++++++++++++++++++++
 mkdocs.yml                          | 14 +-----
 15 files changed, 101 insertions(+), 62 deletions(-)
 delete mode 100644 docs/howtos/pybis/collections.md
 delete mode 100644 docs/howtos/pybis/datasets.md
 delete mode 100644 docs/howtos/pybis/objects.md
 delete mode 100644 docs/howtos/pybis/objects_props.md
 delete mode 100644 docs/howtos/pybis/parent_child.md
 delete mode 100644 docs/howtos/pybis/projects.md
 delete mode 100644 docs/howtos/pybis/searches.md
 delete mode 100644 docs/howtos/pybis/setup.md
 delete mode 100644 docs/howtos/pybis/spaces.md
 delete mode 100644 docs/tutorials/create-masterdata.md
 delete mode 100644 docs/tutorials/pybis.md
 create mode 100644 docs/tutorials/tutorial.md

diff --git a/docs/howtos/pybis/collections.md b/docs/howtos/pybis/collections.md
deleted file mode 100644
index 87398cc..0000000
--- a/docs/howtos/pybis/collections.md
+++ /dev/null
@@ -1,3 +0,0 @@
-
-!!! warning
-    This page is still under construction.
\ No newline at end of file
diff --git a/docs/howtos/pybis/datasets.md b/docs/howtos/pybis/datasets.md
deleted file mode 100644
index 87398cc..0000000
--- a/docs/howtos/pybis/datasets.md
+++ /dev/null
@@ -1,3 +0,0 @@
-
-!!! warning
-    This page is still under construction.
\ No newline at end of file
diff --git a/docs/howtos/pybis/objects.md b/docs/howtos/pybis/objects.md
deleted file mode 100644
index 87398cc..0000000
--- a/docs/howtos/pybis/objects.md
+++ /dev/null
@@ -1,3 +0,0 @@
-
-!!! warning
-    This page is still under construction.
\ No newline at end of file
diff --git a/docs/howtos/pybis/objects_props.md b/docs/howtos/pybis/objects_props.md
deleted file mode 100644
index 87398cc..0000000
--- a/docs/howtos/pybis/objects_props.md
+++ /dev/null
@@ -1,3 +0,0 @@
-
-!!! warning
-    This page is still under construction.
\ No newline at end of file
diff --git a/docs/howtos/pybis/parent_child.md b/docs/howtos/pybis/parent_child.md
deleted file mode 100644
index 87398cc..0000000
--- a/docs/howtos/pybis/parent_child.md
+++ /dev/null
@@ -1,3 +0,0 @@
-
-!!! warning
-    This page is still under construction.
\ No newline at end of file
diff --git a/docs/howtos/pybis/projects.md b/docs/howtos/pybis/projects.md
deleted file mode 100644
index 87398cc..0000000
--- a/docs/howtos/pybis/projects.md
+++ /dev/null
@@ -1,3 +0,0 @@
-
-!!! warning
-    This page is still under construction.
\ No newline at end of file
diff --git a/docs/howtos/pybis/searches.md b/docs/howtos/pybis/searches.md
deleted file mode 100644
index 87398cc..0000000
--- a/docs/howtos/pybis/searches.md
+++ /dev/null
@@ -1,3 +0,0 @@
-
-!!! warning
-    This page is still under construction.
\ No newline at end of file
diff --git a/docs/howtos/pybis/setup.md b/docs/howtos/pybis/setup.md
deleted file mode 100644
index 87398cc..0000000
--- a/docs/howtos/pybis/setup.md
+++ /dev/null
@@ -1,3 +0,0 @@
-
-!!! warning
-    This page is still under construction.
\ No newline at end of file
diff --git a/docs/howtos/pybis/spaces.md b/docs/howtos/pybis/spaces.md
deleted file mode 100644
index 87398cc..0000000
--- a/docs/howtos/pybis/spaces.md
+++ /dev/null
@@ -1,3 +0,0 @@
-
-!!! warning
-    This page is still under construction.
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index 9496fcc..8b013cd 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -4,7 +4,7 @@ hide: toc
 
 # Welcome to the `bam-masterdata` documentation page.
 
-The `bam-masterdata` is a Python package used to define and handle the data model defined in the BAM Data Store project. The BAM Data Store is the central system for Research Data Management at the Bundesanstalt für Materialforschung und -prüfung (BAM). It is a modified instance of [openBIS](https://openbis.ch/).
+The `bam-masterdata` is a Python package designed to define and handle the Masterdata used in the BAM Data Store project. The BAM Data Store is the central system for Research Data Management at the Bundesanstalt für Materialforschung und -prüfung (BAM). It is a customized instance of [openBIS](https://openbis.ch/).
 <!-- This documentation page is divided according to the [diataxis method](https://www.diataxis.fr/). -->
 
 
@@ -14,9 +14,7 @@ The `bam-masterdata` is a Python package used to define and handle the data mode
 
 <h3>Tutorials</h3>
 
-The **Tutorials** are designed to guide you through the general and basic understanding of the functionalities. These are intended for learning the software in a first approach.
-
-- [Creating Masterdata](tutorials/create-masterdata.md)
+The **Tutorials** are designed to guide you through the general and basic functionalities of the package. They are ideal for learning the software during your first interaction.
 
 </div>
 
@@ -24,7 +22,7 @@ The **Tutorials** are designed to guide you through the general and basic unders
 
 <h3>How-to guides</h3>
 
-The **How-to guides** provide step-by-step instructions for a wide range of tasks. These are oriented for a practical application so you can use them as a fast entry point when searching for specific information.
+The **How-to guides** provide step-by-step instructions for a variety of tasks. These serve as a quick reference for practical applications when you need specific information.
 
 
 </div>
@@ -33,7 +31,7 @@ The **How-to guides** provide step-by-step instructions for a wide range of task
 
 <h3>Explanations</h3>
 
-The **Explanations** give you a theoretical background about the main concepts. These are overlapping with BAM Data Store, openBIS and pyBIS concepts, but also some specific BAM Masterdata ones.
+The **Explanations** offer theoretical insights into the core concepts.
 
 </div>
 
@@ -41,7 +39,7 @@ The **Explanations** give you a theoretical background about the main concepts.
 
 <h3>References</h3>
 
-The **References** include the glossary of used terms and API documentation.
+The **References** include a glossary of terms and the automatically generated API documentation.
 
 </div>
 
@@ -49,5 +47,5 @@ The **References** include the glossary of used terms and API documentation.
 
 
 ## Contact
-Many parts of this documentation are currently under construction. If you have further questions that are not yet answered here, please contact [datastore@bam.de](mailto:datastore@bam.de).
+This documentation is a work in progress. If you have questions that are not yet addressed, please contact [datastore@bam.de](mailto:datastore@bam.de).
 
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index 49b7017..8fb5825 100644
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -58,7 +58,7 @@
     --bam-gelb-darkest: rgb(205, 125, 0);
 
     /* Backgrounds, primaries, and secondaries */
-    --background-light: var(--bam-weiss);
+    --background-light: var(--bam-schwar);
     --color-light: var(--bam-schwarz-100);
     --background-dark: var(--bam-schwarz-100);
     --color-dark: var(--bam-weiss);
@@ -70,9 +70,9 @@
 
     --grid-background-light: rgb(238, 229, 174, 0.5);
 
-    --md-primary-fg-color: var(--bam-rot-dark);  /* for hrefs */
-    --md-accent-fg-color: var(--bam-rot);  /* when hovering hrefs */
-    --md-primary-bg-color: var(--bam-rot);  /* for search icon */
+    --md-primary-fg-color: var(--bam-blau-darker);  /* for hrefs */
+    --md-accent-fg-color: var(--bam-blau-dark);  /* when hovering hrefs */
+    --md-primary-bg-color: var(--bam-blau-darkest);  /* for search icon */
     --md-default-bg-color: var(--bam-weiss);
 }
 
@@ -105,11 +105,11 @@
 }
 
 .md-source {
-    color: var(--bam-rot-dark);
+    color: var(--bam-blau-darkest);
 }
 
 .md-source:hover {
-    color: var(--bam-rot);
+    color: var(--bam-blau-dark);
 }
 
 .md-main {
@@ -148,8 +148,13 @@
     font-size: 0.8rem;
 }
 
+.md-code__content {
+    background-color: var(--bam-weiss-dark) !important;
+}
+
 .md-nav__title {
-    color: var(--bam-schwarz-60)
+    color: var(--bam-schwarz-100);
+    font-size: 1.0rem;
 }
 
 .md-nav--primary .md-nav__title {
@@ -163,4 +168,10 @@
 
 .md-footer {
     background-color: var(--bam-blau-darkest);
-}
\ No newline at end of file
+}
+
+.md-nav--secondary .md-nav__title{
+    background-color: transparent;
+    z-index: 2;
+    box-shadow: 0 0 -.4rem .4rem var(--md-default-bg-color);
+}
diff --git a/docs/tutorials/create-masterdata.md b/docs/tutorials/create-masterdata.md
deleted file mode 100644
index 87398cc..0000000
--- a/docs/tutorials/create-masterdata.md
+++ /dev/null
@@ -1,3 +0,0 @@
-
-!!! warning
-    This page is still under construction.
\ No newline at end of file
diff --git a/docs/tutorials/pybis.md b/docs/tutorials/pybis.md
deleted file mode 100644
index 87398cc..0000000
--- a/docs/tutorials/pybis.md
+++ /dev/null
@@ -1,3 +0,0 @@
-
-!!! warning
-    This page is still under construction.
\ No newline at end of file
diff --git a/docs/tutorials/tutorial.md b/docs/tutorials/tutorial.md
new file mode 100644
index 0000000..10ae6bb
--- /dev/null
+++ b/docs/tutorials/tutorial.md
@@ -0,0 +1,75 @@
+## Installation setup
+
+You can install the package in two methods:
+
+- using `pip` as an additional package to your project,
+- as a developer, cloning and installing the repository locally
+
+### Installing with `pip`
+
+We recommend you to create first a virtual environment, either with [`conda`](https://anaconda.org/anaconda/conda) or with [`venv`](https://docs.python.org/3/library/venv.html). Note that `bam-masterdata` can be installed with any Python version between 3.9 and 3.12.
+
+**Conda**
+
+Run:
+```sh
+conda create --name .venv pip python=3.12
+conda activate .venv
+```
+
+**Venv**
+
+Run:
+```sh
+python3.12 -m venv .venv
+source .venv/bin/activate
+```
+
+After creating and activating your environment, make sure you have `pip` upgraded, and install the package:
+```sh
+pip install --upgrade pip
+pip install bam-masterdata
+```
+
+### Development
+
+In order to develop the package, first you have to clone the repository:
+```sh
+git clone https://git.bam.de/bam-data-store/bam-masterdata.git
+cd bam-masterdata
+```
+
+Same as before, create a virtual environment (in this example, we use `venv`) and activate it:
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Run the following script:
+
+```sh
+./scripts/install_python_dependencies.sh
+```
+
+??? info "Installation script"
+    The script contains a set of steps which ensure to install the package with all optional dependencies. If you prefer to install manually, we recommend you to take a look into the script and install only the desired dependencies.
+
+    Its content is:
+    ```sh
+    #!/bin/bash
+
+    # Fail immediately if any command exits with a non-zero status
+    set -e
+
+    echo "Making sure pip is up to date..."
+    pip install --upgrade pip
+
+    echo "Installing uv..."
+    pip install uv
+
+    echo "Installing main project dependencies..."
+    uv pip install -e '.[dev,docu]'
+
+    echo "All dependencies installed successfully."
+    ```
diff --git a/mkdocs.yml b/mkdocs.yml
index 2ef33f4..e0a44b7 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -4,21 +4,9 @@ site_author: BAM Data Store
 repo_url: https://github.com/BAMresearch/bam-masterdata
 nav:
   - Home: index.md
-  - Tutorial:
-    - Create Masterdata: tutorials/create-masterdata.md
-    - Basic pyBIS usage: tutorials/pybis.md
+  - Tutorial: tutorials/tutorial.md
   - How-to guides:
     - Overview: howtos/overview.md
-    - pyBIS:
-      - Initial setup: howtos/pybis/setup.md
-      - Create spaces: howtos/pybis/spaces.md
-      - Create projects: howtos/pybis/projects.md
-      - Create collections: howtos/pybis/collections.md
-      - Create objects: howtos/pybis/objects.md
-      - Modify objects properties: howtos/pybis/objects_props.md
-      - Define parent-child relationships: howtos/pybis/parent_child.md
-      - Create datasets: howtos/pybis/datasets.md
-      - Searches and filters: howtos/pybis/searches.md
   - Explanations:
     - Data Store: explanations/data-store.md
     - OpenBIS : explanations/openbis.md