From 0ec0fc1a51407509bc0a5b0738a6c073f18aacd5 Mon Sep 17 00:00:00 2001
From: Henry Luetcke <hluetcke@ethz.ch>
Date: Mon, 5 Aug 2024 15:16:35 +0200
Subject: [PATCH] improve html output formatting
---
RRP-User-Documentation.html | 70 +++++++++++++++++++------------------
metadata.yaml | 2 +-
rrp-docs.md | 19 +++++-----
3 files changed, 47 insertions(+), 44 deletions(-)
diff --git a/RRP-User-Documentation.html b/RRP-User-Documentation.html
index 4928466..5830ab9 100644
--- a/RRP-User-Documentation.html
+++ b/RRP-User-Documentation.html
@@ -8,6 +8,7 @@
<title>RRP User Documentation</title>
<style>
html {
+font-size: 22px;
color: #1a1a1a;
background-color: #fdfdfd;
}
@@ -246,21 +247,19 @@ Platform (RRP) </p>
<nav id="TOC" role="doc-toc">
<h2 id="toc-title">Table of Contents</h2>
<ul>
-<li><a href="#rrp-user-documentation" id="toc-rrp-user-documentation"><span class="toc-section-number">1</span> RRP User Documentation</a>
-<ul>
-<li><a href="#prerequisites" id="toc-prerequisites"><span class="toc-section-number">1.1</span> Prerequisites</a></li>
-<li><a href="#mounting-openbis-datasets" id="toc-mounting-openbis-datasets"><span class="toc-section-number">1.2</span> Mounting openBIS datasets</a></li>
-<li><a href="#creating-a-project" id="toc-creating-a-project"><span class="toc-section-number">1.3</span> Creating a project</a></li>
-<li><a href="#starting-a-project-and-working-with-jupyterlab" id="toc-starting-a-project-and-working-with-jupyterlab"><span class="toc-section-number">1.4</span> Starting a project and working
-with JupyterLab</a></li>
-<li><a href="#saving-results-and-uploading-to-openbis" id="toc-saving-results-and-uploading-to-openbis"><span class="toc-section-number">1.5</span> Saving results and uploading to
+<li><a href="#prerequisites" id="toc-prerequisites"><span class="toc-section-number">1</span> Prerequisites</a></li>
+<li><a href="#mounting-openbis-datasets" id="toc-mounting-openbis-datasets"><span class="toc-section-number">2</span> Mounting openBIS datasets</a></li>
+<li><a href="#creating-a-project" id="toc-creating-a-project"><span class="toc-section-number">3</span> Creating a project</a></li>
+<li><a href="#starting-a-project-and-working-with-jupyterlab" id="toc-starting-a-project-and-working-with-jupyterlab"><span class="toc-section-number">4</span> Starting a project and working with
+JupyterLab</a></li>
+<li><a href="#saving-results-and-uploading-to-openbis" id="toc-saving-results-and-uploading-to-openbis"><span class="toc-section-number">5</span> Saving results and uploading to
openBIS</a></li>
-<li><a href="#sharing-a-project" id="toc-sharing-a-project"><span class="toc-section-number">1.6</span> Sharing a project</a></li>
-</ul></li>
+<li><a href="#sharing-a-project" id="toc-sharing-a-project"><span class="toc-section-number">6</span> Sharing a project</a></li>
</ul>
</nav>
-<h1 data-number="1" id="rrp-user-documentation"><span class="header-section-number">1</span> RRP User Documentation</h1>
-<h2 data-number="1.1" id="prerequisites"><span class="header-section-number">1.1</span> Prerequisites</h2>
+<h1 data-number="1" id="prerequisites"><span class="header-section-number">1</span> Prerequisites</h1>
+<p>To use RRP efficiently, the following basic requirements must be
+fullfilled:</p>
<ol type="1">
<li>Accessible public or private Git repository (e.g. GitLab or
GitHub)</li>
@@ -272,7 +271,7 @@ repository. For details see <a href="https://repo2docker.readthedocs.io/en/lates
<li>Access to openBIS server. Currently each RRP server is linked to one
openBIS server.</li>
</ol>
-<h2 data-number="1.2" id="mounting-openbis-datasets"><span class="header-section-number">1.2</span> Mounting openBIS datasets</h2>
+<h1 data-number="2" id="mounting-openbis-datasets"><span class="header-section-number">2</span> Mounting openBIS datasets</h1>
<p>RRP projects can access datasets stored in the openBIS server.
Selected datasets are mounted directly on the RRP server for read-only
access. To specify which datasets should be mounted, add a folder called
@@ -289,7 +288,7 @@ to be mounted by RRP</li>
</ul>
<p>It is also possible to add datasets to be mounted in the RRP UI once
a project has been created (see below).</p>
-<h2 data-number="1.3" id="creating-a-project"><span class="header-section-number">1.3</span> Creating a project</h2>
+<h1 data-number="3" id="creating-a-project"><span class="header-section-number">3</span> Creating a project</h1>
<ol type="1">
<li>Login to the RRP server with your openBIS user credentials.</li>
<li>Select the <strong>+</strong> button next to <strong>Your
@@ -302,8 +301,8 @@ Next select <strong>Build</strong>. This will build the Docker image
from the repository. This step will take several minutes to
complete.</li>
</ol>
-<h2 data-number="1.4" id="starting-a-project-and-working-with-jupyterlab"><span class="header-section-number">1.4</span> Starting a project and working
-with JupyterLab</h2>
+<h1 data-number="4" id="starting-a-project-and-working-with-jupyterlab"><span class="header-section-number">4</span> Starting a project and working
+with JupyterLab</h1>
<ol type="1">
<li>Once the build of the project is complete, it will be listed under
Your project, with Status: not running.</li>
@@ -320,8 +319,8 @@ UI.</li>
<li>Results to be uploaded back to openBIS can be stored in the folder
<code>results</code> (see below).</li>
</ol>
-<h2 data-number="1.5" id="saving-results-and-uploading-to-openbis"><span class="header-section-number">1.5</span> Saving results and uploading to
-openBIS</h2>
+<h1 data-number="5" id="saving-results-and-uploading-to-openbis"><span class="header-section-number">5</span> Saving results and uploading to
+openBIS</h1>
<ol type="1">
<li>A list of results files for the project is shown in the Results tab
of the RRP project.</li>
@@ -330,24 +329,27 @@ project.</li>
<li>Fill the openBIS destination identifier in which the results dataset
should be created. You can specify either a permId or the path to the
experiment / project.</li>
-<li>Select the dataset type (e.g. <code>ANALYZED_DATA</code>) and
-specify some dataset properties. Then click on <strong>Create
+<li>Select the dataset type (e.g. <code class="sourceCode bash"><span class="ex">ANALYZED_DATA</span></code>)
+and specify some dataset properties. Then click on <strong>Create
dataset</strong>.</li>
</ol>
-<h2 data-number="1.6" id="sharing-a-project"><span class="header-section-number">1.6</span> Sharing a project</h2>
+<h1 data-number="6" id="sharing-a-project"><span class="header-section-number">6</span> Sharing a project</h1>
<p>RRP projects can be shared with other users of the same server
-(e.g. fellow lab members, PI etc.). 1. Switch to the Share tab of the
-RRP project. Any existing share identifiers are listed under Active
-share identifiers. 2. To create a new share identifier, enter a
-description and commit. Note that the local Git repository on the RRP
-server has to be clean and up-to-date before a share identifier can be
-created. To achieve this, first commit and push any local changes. 3.
-Next, select <strong>Create share identifier</strong>. If successfull,
-the new share identifier will be listed above. Share it with colleagues
-either by mail or chat. 4. To create a new project from a share
-identifier, select the <strong>+</strong> button next to <strong>Your
-projects</strong> and click “Create new project from Share identifierâ€.
-Enter the identifier and user credentials, then click
-<strong>Clone</strong>.</p>
+(e.g. fellow lab members, PI etc.):</p>
+<ol type="1">
+<li>Switch to the Share tab of the RRP project. Any existing share
+identifiers are listed under Active share identifiers.</li>
+<li>To create a new share identifier, enter a description and commit.
+Note that the local Git repository on the RRP server has to be clean and
+up-to-date before a share identifier can be created. To achieve this,
+first commit and push any local changes.</li>
+<li>Next, select <strong>Create share identifier</strong>. If
+successfull, the new share identifier will be listed above. Share it
+with colleagues either by mail or chat.</li>
+<li>To create a new project from a share identifier, select the
+<strong>+</strong> button next to <strong>Your projects</strong> and
+click “Create new project from Share identifierâ€. Enter the identifier
+and user credentials, then click <strong>Clone</strong>.</li>
+</ol>
</body>
</html>
diff --git a/metadata.yaml b/metadata.yaml
index 2b55182..48c1e85 100644
--- a/metadata.yaml
+++ b/metadata.yaml
@@ -13,4 +13,4 @@ standalone: true
self-contained: true
table-of-contents: false
number-sections: true
-highlight-style: kate
+highlight-style: kate
\ No newline at end of file
diff --git a/rrp-docs.md b/rrp-docs.md
index 38d99e9..2a4feb1 100644
--- a/rrp-docs.md
+++ b/rrp-docs.md
@@ -1,11 +1,11 @@
-# RRP User Documentation
+# Prerequisites
+To use RRP efficiently, the following basic requirements must be fullfilled:
-## Prerequisites
1. Accessible public or private Git repository (e.g. GitLab or GitHub)
2. Specification of the execution environment for the Git repository. RRP uses [repo2docker](https://repo2docker.readthedocs.io/en/latest/index.html) to build a Docker image from the source repository. The execution environment can be determined with configuration files in the repository. For details see [here](https://repo2docker.readthedocs.io/en/latest/config_files.html#config-files).
3. Access to openBIS server. Currently each RRP server is linked to one openBIS server.
-## Mounting openBIS datasets
+# Mounting openBIS datasets
RRP projects can access datasets stored in the openBIS server. Selected datasets are mounted directly on the RRP server for read-only access. To specify which datasets should be mounted, add a folder called `.rrp` to your Git repository. In this folder, add a file called `datasets.yaml` with following content:
```{.yaml .number-lines}
@@ -20,13 +20,13 @@ destinations:
It is also possible to add datasets to be mounted in the RRP UI once a project has been created (see below).
-## Creating a project
+# Creating a project
1. Login to the RRP server with your openBIS user credentials.
2. Select the **+** button next to **Your projects** and click "Create new project from Git repository"
3. Specify the repository URL and user credentials (for private repos), then select **Clone**.
4. Select a name for the project as well as Git branch, tag or commit. Next select **Build**. This will build the Docker image from the repository. This step will take several minutes to complete.
-## Starting a project and working with JupyterLab
+# Starting a project and working with JupyterLab
1. Once the build of the project is complete, it will be listed under Your project, with Status: not running.
2. Select the "Play" button to start the project. Status will switch to "processing" and then to "running".
3. Select the "Launch" button to start the JupyterLab UI in a new browser tab / window.
@@ -35,14 +35,15 @@ It is also possible to add datasets to be mounted in the RRP UI once a project h
6. Mounted openBIS datasets are available in the folder `openbis`.
7. Results to be uploaded back to openBIS can be stored in the folder `results` (see below).
-## Saving results and uploading to openBIS
+# Saving results and uploading to openBIS
1. A list of results files for the project is shown in the Results tab of the RRP project.
2. To upload results to openBIS, select the Upload tab of the RRP project.
3. Fill the openBIS destination identifier in which the results dataset should be created. You can specify either a permId or the path to the experiment / project.
-4. Select the dataset type (e.g. `ANALYZED_DATA`) and specify some dataset properties. Then click on **Create dataset**.
+4. Select the dataset type (e.g. `ANALYZED_DATA`{.bash}) and specify some dataset properties. Then click on **Create dataset**.
+
+# Sharing a project
+RRP projects can be shared with other users of the same server (e.g. fellow lab members, PI etc.):
-## Sharing a project
-RRP projects can be shared with other users of the same server (e.g. fellow lab members, PI etc.).
1. Switch to the Share tab of the RRP project. Any existing share identifiers are listed under Active share identifiers.
2. To create a new share identifier, enter a description and commit. Note that the local Git repository on the RRP server has to be clean and up-to-date before a share identifier can be created. To achieve this, first commit and push any local changes.
3. Next, select **Create share identifier**. If successfull, the new share identifier will be listed above. Share it with colleagues either by mail or chat.
--
GitLab