Update and move SWAN-specific instructions (#254)

* docs: update SWAN-specific instructions

* Update and move from Getting_started.ipynb to setup.rst.

* docs: mention opening a JIRA issue after release

README.md

@@ -25,7 +25,7 @@ If you are not sure about your Python environment, please also see below how to
 
 ## Getting started
 
-For using `hepdata_lib`, you don't even need to install it, but can use the [binder](https://mybinder.org/) or [SWAN](https://swan.cern.ch/) (CERN-only) services using one of the buttons below and following the instructions in the notebook with name [Getting_started](examples/Getting_started.ipynb):
+For using `hepdata_lib`, you don't even need to install it, but can use the [binder](https://mybinder.org/) or [SWAN](https://swan.cern.ch/) (CERN-only) services using one of the buttons below:
 
 [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/HEPData/hepdata_lib/main?filepath=examples/Getting_started.ipynb)
 [![SWAN](https://swanserver.web.cern.ch/swanserver/images/badge_swan_white_150.png)](https://cern.ch/swanserver/cgi-bin/go/?projurl=https://github.com/HEPData/hepdata_lib.git)

docs/dev.rst

@@ -121,4 +121,17 @@ Analysing the code
     pylint hepdata_lib/*.py
     pylint tests/*.py --rcfile=tests/pylintrc
 
-These commands are run by GitHub Actions, so you should first check locally that no issues are flagged.
+These commands are run by GitHub Actions, so you should first check locally that no issues are flagged.
+
+
+Making a release
+----------------
+
+After making a new release available on `PyPI`_, a `JIRA`_ issue (`example`_) should be opened to request that
+``hepdata_lib`` is upgraded in future `LCG Releases`_ used by `SWAN`_.
+
+.. _PyPI: https://pypi.org/project/hepdata-lib/
+.. _JIRA: https://its.cern.ch/jira/projects/SPI/
+.. _example: https://its.cern.ch/jira/browse/SPI-2507
+.. _LCG Releases: https://lcginfo.cern.ch/pkg/hepdata_lib/
+.. _SWAN: http://swan.cern.ch/

docs/setup.rst

@@ -34,6 +34,21 @@ On LXPLUS and many other local computing sites with CVMFS and Apptainer (previou
 This opens a new shell with ``hepdata_lib``, ROOT, and Python 3 available.
 Your home directory and most other user directories on the machine on which you execute Apptainer will also be accessible from within this shell.
 
+Using SWAN
+++++++++++
+
+`SWAN`_ requires a CERN account. ``hepdata_lib`` should already be installed in most recent `LCG Releases`_ used by
+SWAN. The latest LCG Release might not contain the latest ``hepdata_lib`` version. The `LCG Nightly`_, possibly
+containing a more recent ``hepdata_lib`` version, can be used by selecting the "Bleeding Edge" software stack in the
+SWAN configuration. Alternatively, you can upgrade ``hepdata_lib`` by adding a local installation path to the
+``$PYTHONPATH`` in a startup script specified as the "Environment script" in the SWAN configuration (see
+`Install packages in CERNBox`_). Then execute ``!pip install hepdata_lib --user --upgrade`` in your Jupyter notebook
+to upgrade ``hepdata_lib`` to the latest version.
+
+.. _SWAN: http://swan.cern.ch/
+.. _LCG Releases: https://lcginfo.cern.ch/pkg/hepdata_lib/
+.. _LCG Nightly: https://lcginfo.cern.ch/#nightlies
+.. _Install packages in CERNBox: https://swan.docs.cern.ch/advanced/install_packages/
 
 .. _sec-setup-developers:
 

examples/Getting_started.ipynb

@@ -6,15 +6,7 @@
    "source": [
     "# Getting started with hepdata_lib\n",
     "\n",
-    "The following instructions and examples should get you started to get your analysis into [HEPData](https://hepdata.net) using `hepdata_lib`. Please also refer to the [documentation](http://hepdata-lib.readthedocs.io/). While you can also run `hepdata_lib` on your local computer, you can use the [binder](https://mybinder.org/) or [SWAN](http://swan.cern.ch/) services in the browser. Mind that SWAN is only available for people with a CERN account.\n",
-    "\n",
-    "## SWAN-specific instructions\n",
-    "\n",
-    "For SWAN, if you haven't done so already, open up a new terminal (going back to the project tab and clicking the terminal icon in the top right), and enter the following to install `hepdata_lib`:\n",
-    "```\n",
-    "pip install --user hepdata_lib\n",
-    "```\n",
-    "Then go back to the notebook."
+    "The following instructions and examples should get you started to get your analysis into [HEPData](https://hepdata.net) using `hepdata_lib`. Please also refer to the [documentation](http://hepdata-lib.readthedocs.io/). While you can also run `hepdata_lib` on your local computer, you can use the [binder](https://mybinder.org/) or [SWAN](http://swan.cern.ch/) services in the browser. Mind that SWAN is only available for people with a CERN account."
    ]
   },
   {
@@ -35,12 +27,14 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Welcome to JupyROOT 6.28/06\n"
+      "Welcome to JupyROOT 6.26/06\n",
+      "hepdata_lib version 0.14.1\n"
      ]
     }
    ],
    "source": [
-    "import hepdata_lib"
+    "import hepdata_lib\n",
+    "print(\"hepdata_lib version\", hepdata_lib.__version__)"
    ]
   },
   {
@@ -396,7 +390,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.6"
+   "version": "3.10.12"
   }
  },
  "nbformat": 4,