fix several docs issues

OpenCOMPES · Oct 23, 2024 · 821d00d · 821d00d
1 parent 29d4d1a
commit 821d00d
Show file tree

Hide file tree

Showing 7 changed files with 36 additions and 54 deletions.
diff --git a/docs/index.md b/docs/index.md
@@ -13,8 +13,12 @@ SED (Single Event Data Frame) is a collection of routines and utilities to handl
 It features lazy evaluation of dataframe processing using dask, numba-accelerated multi-dimensional binning, calibration and correction for trARPES (Time- and angle-resolved photoemission spectroscopy) datasets.
 The package ensures provenance and FAIR data through metadata tracking, usage of the community defined NeXus format.
 
+## User guide
+
+We introduce different functionalities of the package by several step-by-step use guides:
+
 ```{toctree}
-:maxdepth: 2
+:maxdepth: 1
 
 user_guide/index
 
@@ -30,16 +34,6 @@ Several example notebooks to demonstrate the functionality of SED for end-to-end
 workflows/index
 ```
 
-## Advanced topics
-
-There are also further example notebooks showing more advanced topics not required in every-day analysis.
-
-```{toctree}
-:maxdepth: 2
-
-advanced_topics/index
-```
-
 ## API
 
 ```{toctree}

diff --git a/docs/sed/dataset.rst b/docs/sed/dataset.rst
@@ -13,14 +13,12 @@ Getting datasets
    import os
    from sed.dataset import dataset
 
-Get
-~~~
+get()
+^^^^^
 
 The “get” just needs the data name, but another root_dir can be provided.
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Try to interrupt the download process and restart to see that it continues the download from where it stopped
-'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 .. code:: python
 
@@ -39,14 +37,12 @@ Try to interrupt the download process and restart to see that it continues the d
    Download complete.
 
 Not providing “remove_zip” at all will by default delete the zip file after extraction
-''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 .. code:: python
 
    dataset.get("WSe2")
 
 Setting the “use_existing” keyword to False allows to download the data in another location. Default is to use existing data
-''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 .. code:: python
 
@@ -62,10 +58,8 @@ Setting the “use_existing” keyword to False allows to download the data in a
 
 
 Interrupting extraction has similar behavior to download and just continues from where it stopped.
-''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 Or if user deletes the extracted documents, it re-extracts from zip file
-'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 .. code:: python
 
@@ -90,11 +84,12 @@ Or if user deletes the extracted documents, it re-extracts from zip file
 
    WSe2 data extracted successfully.
 
+remove()
+^^^^^^^^
+
 “remove” allows removal of some or all instances of existing data
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This would remove only one of the two existing paths
-''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 .. code:: python
 
@@ -105,7 +100,6 @@ This would remove only one of the two existing paths
    Removed <user_path>/datasets/WSe2
 
 This removes all instances, if any present
-''''''''''''''''''''''''''''''''''''''''''
 
 .. code:: python
 
@@ -116,10 +110,9 @@ This removes all instances, if any present
    WSe2 data is not present.
 
 Attributes useful for user
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 All available datasets after looking at module, user and folder levels
-''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 .. code:: python
 
@@ -130,7 +123,6 @@ All available datasets after looking at module, user and folder levels
    ['WSe2', 'TaS2', 'Gd_W110']
 
 The dir and subdirs where data is located
-'''''''''''''''''''''''''''''''''''''''''
 
 .. code:: python
 
@@ -150,7 +142,6 @@ The dir and subdirs where data is located
     '<user_path>/datasets/WSe2/energycal_2019_01_08']
 
 Existing locations where data is present
-''''''''''''''''''''''''''''''''''''''''
 
 .. code:: python
 
@@ -164,22 +155,21 @@ Existing locations where data is present
 Example of adding custom datasets
 ---------------------------------
 
+DatasetsManager
+^^^^^^^^^^^^^^^
+
 Allows to add or remove datasets in json file at any level (module, user, folder).
-''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 Looks at all levels to give the available datasets
-''''''''''''''''''''''''''''''''''''''''''''''''''
 
 .. code:: python
 
    import os
    from sed.dataset import DatasetsManager
 
 We add a new dataset to both folder and user levels
-'''''''''''''''''''''''''''''''''''''''''''''''''''
 
 This dataset also has “rearrange_files” set to True, which takes all files in subfolders and puts them in the main dataset specific directory
-'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 .. code:: python
 
@@ -198,7 +188,6 @@ This dataset also has “rearrange_files” set to True, which takes all files i
    Added Example dataset to user datasets.json
 
 datasets.json should be available in execution folder after this
-''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 .. code:: python
 
@@ -210,7 +199,6 @@ datasets.json should be available in execution folder after this
    ['Example', 'WSe2', 'TaS2', 'Gd_W110']
 
 This will remove the Example dataset from the user json file
-''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 .. code:: python
 
@@ -221,7 +209,6 @@ This will remove the Example dataset from the user json file
    Removed Example dataset from user datasets.json
 
 Adding dataset that already exists will give an error. Likewise, removing one that doesn’t exist
-''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 .. code:: python
 
@@ -234,7 +221,6 @@ Adding dataset that already exists will give an error. Likewise, removing one th
 
 
 Now that dataset.json with Example exists in current dir, lets try to fetch it
-''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 .. code:: python
 
@@ -272,7 +258,6 @@ Now that dataset.json with Example exists in current dir, lets try to fetch it
    []
 
 lets download to another location
-'''''''''''''''''''''''''''''''''
 
 .. code:: python
 
@@ -300,7 +285,6 @@ lets download to another location
    Rearranging complete.
 
 we can remove one instance
-''''''''''''''''''''''''''
 
 .. code:: python
 
@@ -332,7 +316,7 @@ we can remove one instance
    ['<user_path>/datasets/Example']
 
 Default datasets.json
-------------------------
+---------------------
 
 .. literalinclude::  ../../sed/dataset/datasets.json
    :language: json

diff --git a/docs/sed/loader.rst b/docs/sed/loader.rst
@@ -10,6 +10,7 @@ Loader Interface
    :undoc-members:
 
 .. _base_loader:
+
 Abstract BaseLoader
 ###################################################
 .. automodule:: sed.loader.base.loader

diff --git a/docs/advanced_topics/index.md → docs/user_guide/advanced_topics.md b/docs/advanced_topics/index.md → docs/user_guide/advanced_topics.md
@@ -1,12 +1,5 @@
----
-myst:
-  html_meta:
-    "description lang=en": |
-      Advanced topics describing specific workflows and functionalities
----
-# Workflows
-
 ```{toctree}
+:maxdepth: 1
 ../tutorial/6_binning_with_time-stamped_data
 ../tutorial/7_correcting_orthorhombic_symmetry
 ../tutorial/8_jittering_tutorial

diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md
@@ -2,7 +2,7 @@
 myst:
   html_meta:
     "description lang=en": |
-      Documentation for beginner users.
+      Documentation for users.
 ---
 # User Guide
 
@@ -14,12 +14,15 @@ installation
 
 ```{toctree}
 :caption: Basic concepts
+:maxdepth: 1
 ../tutorial/1_binning_fake_data
 ../tutorial/2_conversion_pipeline_for_example_time-resolved_ARPES_data
 ../tutorial/3_metadata_collection_and_export_to_NeXus
+config
 ```
 
 ```{toctree}
-:caption: Advance
-config
+:maxdepth: 1
+:caption: Advanced Topics
+advanced_topics
 ```
diff --git a/tutorial/1_binning_fake_data.ipynb b/tutorial/1_binning_fake_data.ipynb
@@ -20,17 +20,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import sys\n",
-    "\n",
     "import dask\n",
     "import numpy as np\n",
     "import pandas as pd\n",
     "import dask.dataframe\n",
     "\n",
     "import matplotlib.pyplot as plt\n",
     "\n",
-    "sys.path.append(\"../\")\n",
-    "from sed.binning import bin_partition, bin_dataframe"
+    "from sed.binning import bin_partition, bin_dataframe\n",
+    "\n",
+    "%matplotlib widget"
    ]
   },
   {

diff --git a/tutorial/2_conversion_pipeline_for_example_time-resolved_ARPES_data.ipynb b/tutorial/2_conversion_pipeline_for_example_time-resolved_ARPES_data.ipynb
@@ -315,13 +315,21 @@
     "sp.apply_momentum_calibration()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "74e7ef75",
+   "metadata": {},
+   "source": [
+    "## Energy Correction and Calibration workflow"
+   ]
+  },
   {
    "attachments": {},
    "cell_type": "markdown",
    "id": "0bce2388",
    "metadata": {},
    "source": [
-    "## Energy Correction (optional)\n",
+    "### Energy Correction (optional)\n",
     "The purpose of the energy correction is to correct for any momentum-dependent distortion of the energy axis, e.g. from geometric effects in the flight tube, or from space charge"
    ]
   },
@@ -394,7 +402,7 @@
    "id": "8b571b4c",
    "metadata": {},
    "source": [
-    "## 3. Energy calibration\n",
+    "### Energy calibration\n",
     "For calibrating the energy axis, a set of data taken at different bias voltages around the value where the measurement was taken is required."
    ]
   },