docs: Updated installation section, modified rtd options

gh: added a workflow to automatically add a tutorial zip file into any release files.
cseptesting · Sep 25, 2024 · 4a8e76c · 4a8e76c
1 parent 6e299a7
commit 4a8e76c
Show file tree

Hide file tree

Showing 4 changed files with 89 additions and 40 deletions.
diff --git a/.github/workflows/release-tutorials.yml b/.github/workflows/release-tutorials.yml
@@ -0,0 +1,24 @@
+name: Release Tutorials
+
+on:
+  release:
+    types: [ published ]
+
+jobs:
+  upload-tutorials:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out the code
+        uses: actions/checkout@v3
+
+      - name: Zip the tutorials folder
+        run: |
+          zip -r tutorials.zip tutorials/
+
+      - name: Upload the tutorials.zip to the release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: tutorials.zip
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -2,6 +2,7 @@ include README.md
 include CODE_OF_CONDUCT.md
 include requirements.txt
 include requirements_dev.txt
+include environment.yml
 include setup.py
 include setup.cfg
 include pyproject.toml
@@ -14,7 +15,6 @@ graft tests
 graft docs
 prune docs/_build
 prune docs/referenced/generated
-prune docs/tutorials/
 
 global-exclude .git*
 global-exclude *.pyc

diff --git a/docs/conf.py b/docs/conf.py
@@ -60,7 +60,8 @@
 html_theme_options = {
     "display_version": True,
     "prev_next_buttons_location": "both",
-    "collapse_navigation": False,
+    "sticky_navigation": True,
+    "collapse_navigation": True,
     "style_nav_header_background": "#343131ff",
     "logo_only": True,
 }
@@ -79,6 +80,6 @@
         <a href="https://github.com/cseptesting/floatcsep">GitHub</a> |
         <a href="https://cseptesting.org">CSEP Website</a> |
         <a href="https://github.com/sceccode/pycsep">pyCSEP</a> |
-       <a href="https://floatcsep.readthedocs.io/_/downloads/en/latest/pdf/">Download PDF</a>
+        <a href="https://floatcsep.readthedocs.io/_/downloads/en/latest/pdf/">Download PDF</a>
     </div>
-"""
+"""
diff --git a/docs/intro/installation.rst b/docs/intro/installation.rst
@@ -1,20 +1,22 @@
 Installation
 ============
 
-Installing the latest version
------------------------------
+.. important::
 
-    .. important::
+    This application uses ``3.9 <= python <= 3.11``
 
-        This application uses ``python >= 3.9``
 
+Latest Version
+--------------
 
-Using ``conda``
-~~~~~~~~~~~~~~~
+Recommended to learn the software, run the tutorials, and drafting Testing Experiments.
+
+1. Using ``conda``
+~~~~~~~~~~~~~~~~~~
 
 To install **floatCSEP**, first a ``conda`` manager should be installed (https://conda.io). Checkout `Anaconda`, `Miniconda` or `Miniforge` (recommended). Once installed, create an environment with:
 
-    .. code-block:: sh
+    .. code-block:: console
 
         $ conda env create -n csep_env
         $ conda activate csep_env
@@ -23,54 +25,76 @@ Then, clone and install the floatCSEP source code using ``pip``
 
     .. code-block:: console
 
-        git clone https://github.com/cseptesting/floatcsep
-        cd floatcsep
-        pip install .
+        $ git clone https://github.com/cseptesting/floatcsep
+        $ cd floatcsep
+        $ pip install .
 
 
-Using ``pip``
-~~~~~~~~~~~~~
+2. Using ``pip`` only
+~~~~~~~~~~~~~~~~~~~~~
 
-To install using the ``pip`` manager, we require to install the binary dependencies of **pyCSEP** (see `Installing pyCSEP <https://docs.cseptesting.org/getting_started/installing.html>`_}. The **floatcsep** latest version then can be installed as:
+To install using the ``pip`` manager only, we require to install the binary dependencies of **pyCSEP** (see `Installing pyCSEP <https://docs.cseptesting.org/getting_started/installing.html>`_}. The **floatCSEP** latest version can then be installed as:
 
-    .. code-block::
+    .. code-block:: console
 
-        cd ..
-        git clone https://github.com/cseptesting/floatcsep
-        cd floatcsep
-        pip install .
+        $ git clone https://github.com/cseptesting/floatcsep
+        $ cd floatcsep
+        $ python -m venv venv
+        $ pip install .
 
-Installing the stable version
------------------------------
 
+Latest Stable Release
+---------------------
 
-Using ``conda``
-~~~~~~~~~~~~~~~
+Recommended for deploying live Floating Testing Experiments
 
-To install **floatCSEP**, first a ``conda`` manager should be installed (https://conda.io). Checkout `Anaconda`, `Miniconda` or `Miniforge` (recommended). Once installed, create an environment with:
+1. From the ``conda-forge`` channel
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Having a ``conda`` manager installed (https://conda.io), type in a console:
 
-    .. code-block:: sh
+
+    .. code-block:: console
 
         $ conda env create -n csep_env
         $ conda activate csep_env
+        $ conda install -c conda-forge floatcsep
 
-Then, clone and install the floatCSEP source code using ``pip``
+
+2. From the ``PyPI`` repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Having installed the binary dependencies of **pyCSEP** (see `Installing pyCSEP <https://docs.cseptesting.org/getting_started/installing.html>`_}, install **floatCSEP** by:
+
+    .. code-block:: console
+
+        $ python -m venv venv
+        $ pip install floatcsep
+
+.. important::
+    If you want to run the tutorials from a **floatCSEP** installation obtained through ``conda-forge`` or ``PyPI``, the tutorials can be downloaded to your current directory as:
 
     .. code-block:: console
 
-        git clone https://github.com/cseptesting/floatcsep
-        cd floatcsep
-        pip install .
+        $ latest_version=$(curl --silent "https://api.github.com/repos/cseptesting/floatcsep/releases/latest" | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/') && \
+        wget "https://github.com/cseptesting/floatcsep/releases/download/$latest_version/tutorials.zip"
+        $ unzip tutorials.zip -d ./ && rm tutorials.zip
 
+    Or downloaded manually from the `latest release  <https://github.com/cseptesting/floatcsep/releases>`_.
 
-Using ``pip``
-~~~~~~~~~~~~~
 
-To install using the ``pip`` manager, we require to install the binary dependencies of **pyCSEP** (see `Installing pyCSEP <https://docs.cseptesting.org/getting_started/installing.html>`_}. The **floatcsep** latest version can then be installed as:
 
-    .. code-block::
+For Developers
+--------------
+
+It is recommended (not obligatory) to use a ``conda`` environment to make sure your contributions do not depend on your system local libraries. For contributions to the **floatCSEP** codebase, please consider using a `fork <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo>`_ and creating pull-requests from there.
+
+    .. code-block:: console
+
+        $ conda env create -n csep_dev
+        $ conda activate csep_dev
+        $ git clone https://github.com/{your_fork}/floatcsep
+        $ cd floatcsep
+        $ pip install .[dev]
 
-        cd ..
-        git clone https://github.com/cseptesting/floatcsep
-        cd floatcsep
-        pip install .
+This will install (and configure) all the unit-testing, linting and documentation packages.