Added tutorial and clean up docu structure

BAMresearch · Jan 28, 2025 · 866e413 · 866e413 · github-actions · Jan 28, 2025
1 parent 9095881
commit 866e413
Show file tree

Hide file tree

Showing 15 changed files with 101 additions and 62 deletions.
diff --git a/docs/howtos/pybis/collections.md b/docs/howtos/pybis/collections.md
diff --git a/docs/howtos/pybis/datasets.md b/docs/howtos/pybis/datasets.md
diff --git a/docs/howtos/pybis/objects.md b/docs/howtos/pybis/objects.md
diff --git a/docs/howtos/pybis/objects_props.md b/docs/howtos/pybis/objects_props.md
diff --git a/docs/howtos/pybis/parent_child.md b/docs/howtos/pybis/parent_child.md
diff --git a/docs/howtos/pybis/projects.md b/docs/howtos/pybis/projects.md
diff --git a/docs/howtos/pybis/searches.md b/docs/howtos/pybis/searches.md
diff --git a/docs/howtos/pybis/setup.md b/docs/howtos/pybis/setup.md
diff --git a/docs/howtos/pybis/spaces.md b/docs/howtos/pybis/spaces.md
diff --git 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,17 +14,15 @@ 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>
 
 <div markdown="block">
 
 <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,21 +31,21 @@ 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>
 
 <div markdown="block">
 
 <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>
 
 </div>
 
 
 ## Contact
-Many parts of this documentation are currently under construction. If you have further questions that are not yet answered here, please contact [[email protected]](mailto:[email protected]).
+This documentation is a work in progress. If you have questions that are not yet addressed, please contact [[email protected]](mailto:[email protected]).
 
diff --git 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);
-}
+}
+
+.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
diff --git a/docs/tutorials/pybis.md b/docs/tutorials/pybis.md
diff --git a/docs/tutorials/tutorial.md 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
@@ -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
File	Stmts	Miss	Cover	Missing
bam_masterdata
logger.py	8	0	100%
bam_masterdata/cli
cli.py	72	44	44	39%
entities_to_excel.py	54	3	3	94%
entities_to_json.py	36	5	5	86%
excel_to_entities.py	328	314	314	4%
fill_masterdata.py	195	181	181	7%
bam_masterdata/datamodel
collection_types.py	37	0	100%
dataset_types.py	184	184	184	0%
object_types.py	1515	0	100%
property_types.py	800	0	100%
vocabulary_types.py	13721	0	100%
bam_masterdata/metadata
definitions.py	78	0	100%
entities.py	54	3	3	94%
bam_masterdata/openbis
get_entities.py	53	43	43	19%
login.py	6	3	3	50%
bam_masterdata/utils
utils.py	46	7	7	85%
TOTAL	17187	787	95%