switched to pydata theme

freemansw1 · Nov 15, 2024 · 5ec92e6 · 5ec92e6
1 parent 0ebee82
commit 5ec92e6
Show file tree

Hide file tree

Showing 57 changed files with 225 additions and 179 deletions.
diff --git a/doc/conf.py b/doc/conf.py
@@ -3,7 +3,7 @@
 """
 
 # This is the standard readthedocs theme.
-import sphinx_rtd_theme
+import pydata_sphinx_theme
 import sys, os
 
 sys.path.insert(0, os.path.abspath("extensions"))
@@ -23,12 +23,31 @@
 ]
 
 
-html_theme = "sphinx_rtd_theme"
+html_theme = "pydata_sphinx_theme"
 
 html_static_path = ["_static"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
+html_theme_options = {
+    "logo": {
+        "image_light": "images/tobac-logo-colors.png",
+        "image_dark": "images/tobac-logo-colors.png",
+    },
+    # https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/header-links.html#fontawesome-icons
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/tobac-project/tobac",
+            "icon": "fa-brands fa-github",
+        },
+    ],
+    "navbar_start": ["navbar-logo"],
+    "navbar_align": "content",
+    "header_links_before_dropdown": 5,
+}
+
+
 project = "tobac"
 
 master_doc = "index"

diff --git a/doc/code_reviews.rst → doc/developer_guide/code_reviews.rst b/doc/code_reviews.rst → doc/developer_guide/code_reviews.rst
@@ -1,3 +1,5 @@
+.. _code-reviews:
+
 Code reviews
 ------------------
 

diff --git a/doc/code_structure.rst → doc/developer_guide/code_structure.rst b/doc/code_structure.rst → doc/developer_guide/code_structure.rst
@@ -1,4 +1,6 @@
-Code structure and key design concepts 
+.. _code_structure:
+
+Code structure and key design concepts
 --------------------------------------
 
 ==================================

diff --git a/doc/contributing.rst → doc/developer_guide/index.rst b/doc/contributing.rst → doc/developer_guide/index.rst
diff --git a/doc/mentoring.rst → doc/developer_guide/mentoring.rst b/doc/mentoring.rst → doc/developer_guide/mentoring.rst
@@ -1,3 +1,5 @@
+.. _mentoring:
+
 Mentoring and Collaboration
 ----------------------------
 

diff --git a/doc/testing_sphinx-based_rendering.rst → ..._guide/testing_sphinx-based_rendering.rst b/doc/testing_sphinx-based_rendering.rst → ..._guide/testing_sphinx-based_rendering.rst
@@ -1,3 +1,5 @@
+.. _testing-sphinx-rendering:
+
 How to check the Sphinx-based rendering
 ---------------------------------------
 

diff --git a/doc/examples.rst b/doc/examples.rst
diff --git a/doc/data_input.rst → doc/getting_started/data_input.rst b/doc/data_input.rst → doc/getting_started/data_input.rst
@@ -1,6 +1,4 @@
-..
-    Description of the input data required.
-
+.. _data_input:
 
 Data Input
 ==========

diff --git a/doc/feature_detection_overview.rst → ...ng_started/feature_detection_overview.rst b/doc/feature_detection_overview.rst → ...ng_started/feature_detection_overview.rst
@@ -1,4 +1,4 @@
-.. _feature-detection-overview:
+.. _feature_detection_overview:
 
 Feature Detection Basics
 ------------------------
@@ -11,7 +11,7 @@ The feature detection is the first step in using **tobac**.
 
 	Features are identified as regions above or below a sequence of subsequent thresholds (if searching for eather maxima or minima in the data). Subsequently more restrictive threshold values are used to further refine the resulting features and allow for separation of features that are connected through a continuous region of less restrictive threshold values.
 
-	.. image:: images/detection_multiplethresholds.png
+	.. image:: ./images/detection_multiplethresholds.png
             :width: 500 px
 
 **Current development:**

diff --git a/doc/images/cross.png → doc/getting_started/images/cross.png b/doc/images/cross.png → doc/getting_started/images/cross.png
diff --git a/doc/images/decision.png → doc/getting_started/images/decision.png b/doc/images/decision.png → doc/getting_started/images/decision.png
diff --git a/doc/images/detection_multiplethresholds.png → ...d/images/detection_multiplethresholds.png b/doc/images/detection_multiplethresholds.png → ...d/images/detection_multiplethresholds.png
diff --git a/doc/images/linking_prediction.png → ...ing_started/images/linking_prediction.png b/doc/images/linking_prediction.png → ...ing_started/images/linking_prediction.png
diff --git a/doc/images/search.png → doc/getting_started/images/search.png b/doc/images/search.png → doc/getting_started/images/search.png
diff --git a/doc/getting_started/index.rst b/doc/getting_started/index.rst
@@ -0,0 +1,20 @@
+##########################
+  Getting Started
+##########################
+
+.. toctree::
+   :maxdepth: 3
+   :hidden:
+
+   installguide
+   data_input
+   feature_detection_overview
+   tracking_basics
+   segmentation
+   merge_split
+   plotting
+
+
+
+Welcome to *tobac*! We hope that you will find this tracking library to be useful in your research or operational work. To help you get started, we have put together this quickstart guide with some of the basic information you need to know to get started tracking your data with *tobac*.
+
diff --git a/doc/installation.rst → doc/getting_started/installguide.rst b/doc/installation.rst → doc/getting_started/installguide.rst
@@ -1,5 +1,8 @@
+.. _installguide:
+
 Installation
 ------------
+
 tobac works with Python 3 installations.
 
 The easiest way is to install the most recent version of tobac via conda or mamba and the conda-forge channel:

diff --git a/doc/merge_split.rst → doc/getting_started/merge_split.rst b/doc/merge_split.rst → doc/getting_started/merge_split.rst
diff --git a/doc/merge_split_out_vars.csv → doc/getting_started/merge_split_out_vars.csv b/doc/merge_split_out_vars.csv → doc/getting_started/merge_split_out_vars.csv
diff --git a/doc/plotting.rst → doc/getting_started/plotting.rst b/doc/plotting.rst → doc/getting_started/plotting.rst
@@ -1,3 +1,6 @@
+.. _plotting:
+
 Plotting
 ========
+
 tobac provides functions to conveniently visualise the tracking results and analyses.
diff --git a/doc/segmentation.rst → doc/getting_started/segmentation.rst b/doc/segmentation.rst → doc/getting_started/segmentation.rst
diff --git a/doc/linking.rst → doc/getting_started/tracking_basics.rst b/doc/linking.rst → doc/getting_started/tracking_basics.rst
@@ -1,13 +1,15 @@
-Linking
--------
+.. _tracking-basics:
+
+Tracking Basics
+---------------
 Currently implemented options for linking detected features into tracks:
 
 **Trackpy:**
 
 This method uses the trackpy library (http://soft-matter.github.io/trackpy). 
 This approach only takes the point-like position of the feature, e.g. determined as the weighted mean, into account. Features to link with are looked for in a search radius defined by the parameters v_max or d_max. The position of the center of this search radius is determined by the method keyword. method="random" uses the position of the current feature (:math:`t_i`), while method="predict" makes use of the information from the linked feature in the previous timestep (:math:`t_{i-1}`) to predict the next position. For a simple case the search radii of the two methods look like this:
 
-        .. image:: images/linking_prediction.png
+        .. image:: ./images/linking_prediction.png
             :width: 500 px
 
 If there is only one feature in the search radius, the linking can happen immediately. If there are none, the track ends at this timestep. If there are more options, trackpy performs a decision process. Assume there are :math:`N` features in the current and also :math:`N` in the next timeframe and they are all within each search radius. This means there are :math:`N!` options for linking. Each of these options means that :math:`N` distances between the center of the search radius of a current feature and a feature from the next time frame :math:`\delta_n, n=1, 2, ..., N` are traveled by the features. Trackpy will calculate the sum of the squared distances
@@ -18,15 +20,15 @@ If there is only one feature in the search radius, the linking can happen immedi
    
 For every option the lowest value of this sum is used for linking. As an example, consider these two crossing features:
 
-        .. image:: images/cross.png
+        .. image:: ./images/cross.png
             :width: 500 px
 
 If the search radius is chosen large enough, each will contain two options, a horizontal and a diagonal feature:
 
-        .. image:: images/search.png
+        .. image:: ./images/search.png
             :width: 500 px
 
 The linking will look differently for both methods in the end. The horizontal features are closer to the current position than the diagonal ones. This is why these are linked by the "random"-method. On the other hand, the diagonal features lie excatly on the guessed positions for the "predict"-method. This means, that the sum of squared distances is 0 and they are the optimal decision for linking in this case:
 
-        .. image:: images/decision.png
+        .. image:: ./images/decision.png
             :width: 500 px
diff --git a/doc/images/tobac-logo-colors.png b/doc/images/tobac-logo-colors.png
diff --git a/doc/index.rst b/doc/index.rst
@@ -4,11 +4,13 @@
 tobac - Tracking and Object-Based Analysis of Clouds
 -------------------------------------------------------
 
+
+
 **tobac** is a Python package to rapidly identify, track and analyze clouds in different types of gridded datasets, such as 3D model output from cloud-resolving model simulations or 2D data from satellite retrievals.
 
 The software is set up in a modular way to include different algorithms for feature identification, tracking, and analyses. **tobac** is also input variable agnostic and doesn't rely on specific input variables, nor a specific grid to work.
 
-Individual features are identified as either maxima or minima in a 2D or 3D time-varying field (see :doc:`feature_detection_overview`). An associated volume can then be determined using these features with a separate (or identical) time-varying 2D or 3D field and a threshold value (see :doc:`segmentation`). The identified objects are linked into consistent trajectories representing the cloud over its lifecycle in the tracking step. Analysis and visualization methods provide a convenient way to use and display the tracking results.
+Individual features are identified as either maxima or minima in a 2D or 3D time-varying field (see :doc:`getting_started/feature_detection_overview`). An associated volume can then be determined using these features with a separate (or identical) time-varying 2D or 3D field and a threshold value (see :doc:`getting_started/segmentation`). The identified objects are linked into consistent trajectories representing the cloud over its lifecycle in the tracking step. Analysis and visualization methods provide a convenient way to use and display the tracking results.
 
 Version 1.2 of tobac and some example applications are described in a peer-reviewed article in Geoscientific Model Development as:
 
@@ -21,68 +23,21 @@ Sokolowsky, G. A., Freeman, S. W., Jones, W. K., Kukulies, J., Senf, F., Marines
 
 The project is currently being extended by several contributors to include additional workflows and algorithms using the same structure, syntax, and data formats.
 
-.. toctree::
-   :caption: Basic Information
-   :maxdepth: 2
-
-   installation
-   data_input
-   analysis 
-   plotting
-   big_datasets 
-   examples
-   publications
-
-.. toctree::
-   :caption: Feature Detection
-   :maxdepth: 2
-
-   feature_detection_overview
-   threshold_detection_parameters
-   feature_detection/index
-   feature_detection_output
-
-.. toctree::
-   :caption: Segmentation
-   :maxdepth: 2
-
-   segmentation
-   segmentation_parameters
-   segmentation_output
-   features_without_segmented_area
-   transform_segmentation
-
-.. toctree::
-   :caption: Tracking
-   :maxdepth: 2
 
-   linking  
-   tracking_output
-
 .. toctree::
-   :caption: Merge/Split
    :maxdepth: 2
+   :hidden:
 
-   merge_split
-
+   getting_started/index
+   examples/index
+   userguide/index
+   developer_guide/index
 
-.. toctree::
-   :caption: Developer guide
-   :maxdepth: 3
-
-   code_structure
-   contributing
-   code_reviews
-   mentoring
-
-.. toctree:: 
-   :caption: Compute bulk statistics
-   :maxdepth: 2
 
-   bulk_statistics/index
 
 .. toctree::
    :caption: API Reference
    :maxdepth: 3
+   :hidden:
 
    tobac
diff --git a/doc/tobac.rst b/doc/tobac.rst
@@ -1,4 +1,4 @@
-tobac package
+API Documentation
 =============
 
 Submodules

diff --git a/doc/analysis.rst → doc/userguide/analysis.rst b/doc/analysis.rst → doc/userguide/analysis.rst
@@ -1,7 +1,5 @@
-..
-    Documentation of analysis functions
-    TODO: include descriptions of the analysis functions and examples
+.. _analysis-functions:
 
 Analysis
-=========
+========
 tobac provides several analysis functions that allow for the calculation of important quantities based on the tracking results. This includes the calculation of properties such as feature lifetimes and feature areas/volumes, but also allows for a convenient calculation of statistics for arbitrary fields of the same shape as as the input data used for the tracking analysis.
diff --git a/doc/big_datasets.rst → doc/userguide/big_datasets.rst b/doc/big_datasets.rst → doc/userguide/big_datasets.rst
@@ -1,3 +1,5 @@
+.. _handling-big-datasets:
+
 Handling Large Datasets
 -------------------------------------
 

diff --git a/doc/bulk_statistics/index.rst → doc/userguide/bulk_statistics/index.rst b/doc/bulk_statistics/index.rst → doc/userguide/bulk_statistics/index.rst
@@ -1,3 +1,5 @@
+.. _bulk-statistics:
+
 ##########################
   Compute bulk statistics
 ##########################

diff --git a/...statistics_during_feature_detection.ipynb → ...statistics_during_feature_detection.ipynb b/...statistics_during_feature_detection.ipynb → ...statistics_during_feature_detection.ipynb
diff --git a/...pute_statistics_during_segmentation.ipynb → ...pute_statistics_during_segmentation.ipynb b/...pute_statistics_during_segmentation.ipynb → ...pute_statistics_during_segmentation.ipynb
diff --git a/...e_statistics_postprocessing_example.ipynb → ...e_statistics_postprocessing_example.ipynb b/...e_statistics_postprocessing_example.ipynb → ...e_statistics_postprocessing_example.ipynb
diff --git a/doc/feature_detection/index.rst → doc/userguide/feature_detection/index.rst b/doc/feature_detection/index.rst → doc/userguide/feature_detection/index.rst
diff --git a/...tebooks/feature_detection_filtering.ipynb → ...tebooks/feature_detection_filtering.ipynb b/...tebooks/feature_detection_filtering.ipynb → ...tebooks/feature_detection_filtering.ipynb
diff --git a/...tebooks/multiple_thresholds_example.ipynb → ...tebooks/multiple_thresholds_example.ipynb b/...tebooks/multiple_thresholds_example.ipynb → ...tebooks/multiple_thresholds_example.ipynb
diff --git a/...n/notebooks/n_min_threshold_example.ipynb → ...n/notebooks/n_min_threshold_example.ipynb b/...n/notebooks/n_min_threshold_example.ipynb → ...n/notebooks/n_min_threshold_example.ipynb
diff --git a/...otebooks/position_threshold_example.ipynb → ...otebooks/position_threshold_example.ipynb b/...otebooks/position_threshold_example.ipynb → ...otebooks/position_threshold_example.ipynb
diff --git a/doc/feature_detection_3D_out_vars.csv → ...erguide/feature_detection_3D_out_vars.csv b/doc/feature_detection_3D_out_vars.csv → ...erguide/feature_detection_3D_out_vars.csv
diff --git a/doc/feature_detection_base_out_vars.csv → ...guide/feature_detection_base_out_vars.csv b/doc/feature_detection_base_out_vars.csv → ...guide/feature_detection_base_out_vars.csv
diff --git a/doc/feature_detection_output.rst → doc/userguide/feature_detection_output.rst b/doc/feature_detection_output.rst → doc/userguide/feature_detection_output.rst
@@ -1,23 +1,25 @@
+.. _feature-detection-output:
+
 Feature Detection Output
 -------------------------
 
 Feature detection outputs a `pandas` dataframe with several variables. The variables, (with column names listed in the `Variable Name` column), are described below with units. Note that while these variables come initially from the feature detection step, segmentation and tracking also share some of these variables as keys (e.g., the :code:`feature` acts as a universal key between each of these). See :doc:`tracking_output` for the additional columns added by tracking.
 
 Variables that are common to all feature detection files:
 
-.. csv-table:: tobac Feature Detection Output Variables
+.. csv-table:: `tobac` Feature Detection Output Variables
    :file: ./feature_detection_base_out_vars.csv
    :widths: 3, 35, 3, 3
    :header-rows: 1
 
 Variables that are included when using 3D feature detection in addition to those above:
 
-.. csv-table:: tobac 3D Feature Detection Output Variables
+.. csv-table:: `tobac` 3D Feature Detection Output Variables
    :file: ./feature_detection_3D_out_vars.csv
    :widths: 3, 35, 3, 3
    :header-rows: 1
 
 
-One can optionally get the bulk statistics of the data points belonging to each feature regiion or volume. This is done using the `statistics` parameter when calling :ufunc:`tobac.feature_detection_multithreshold` . The user-defined metrics are then added as columns to the output dataframe.  
+One can optionally get the bulk statistics of the data points belonging to each feature region or volume. This is done using the `statistics` parameter when calling :ufunc:`tobac.feature_detection_multithreshold` . The user-defined metrics are then added as columns to the output dataframe.
 
 
diff --git a/doc/features_without_segmented_area.rst → ...guide/features_without_segmented_area.rst b/doc/features_without_segmented_area.rst → ...guide/features_without_segmented_area.rst
@@ -1,3 +1,5 @@
+.. _features-without-segmented-area:
+
 Features without segmented areas
 --------------------------------------
 
@@ -16,7 +18,7 @@ If the segmentation threshold is lower (assuming `target='minimum'`) than the hi
 
 Consider for example the following data with 5 being the highest threshold specified for the Feature Detection (see :doc:`feature_detection_overview`):  
 
-	.. image:: images/features_without_segment.png
+	.. image:: ./images/features_without_segment.png
             :width: 500 px
 
 If the segmentation threshold is larger than 5 (e.g.  `threshold = 6`), the segmented area contains all values <= 5 (still assuming `target='minimum'`), no matter if the detected feature has a threshold lower than 5 (upper panels) or if it is exactly equal to 5 and does not contain any features with lower thresholds inside (lower panels).
@@ -32,7 +34,7 @@ Case 2: Feature position
 
 Another reason for features that do not have a segmented area associated with them is the rare but possible case when the feature position is located outside of the threshold area: 
 
-	.. image:: images/feature_outside_of_threshold_area.png
+	.. image:: ./images/feature_outside_of_threshold_area.png
             :width: 500 px
 
 

diff --git a/doc/images/box_vs_column_seeding.png → ...serguide/images/box_vs_column_seeding.png b/doc/images/box_vs_column_seeding.png → ...serguide/images/box_vs_column_seeding.png
diff --git a/...ges/feature_outside_of_threshold_area.png → ...ges/feature_outside_of_threshold_area.png b/...ges/feature_outside_of_threshold_area.png → ...ges/feature_outside_of_threshold_area.png
diff --git a/...ure_outside_of_threshold_area_extreme.png → ...ure_outside_of_threshold_area_extreme.png b/...ure_outside_of_threshold_area_extreme.png → ...ure_outside_of_threshold_area_extreme.png
diff --git a/doc/images/features_without_segment.png → ...guide/images/features_without_segment.png b/doc/images/features_without_segment.png → ...guide/images/features_without_segment.png
diff --git a/doc/images/position_thresholds.png → doc/userguide/images/position_thresholds.png b/doc/images/position_thresholds.png → doc/userguide/images/position_thresholds.png
diff --git a/doc/images/sat_radar_combined.png → doc/userguide/images/sat_radar_combined.png b/doc/images/sat_radar_combined.png → doc/userguide/images/sat_radar_combined.png
diff --git a/doc/images/sigma_threshold_example.png → ...rguide/images/sigma_threshold_example.png b/doc/images/sigma_threshold_example.png → ...rguide/images/sigma_threshold_example.png
diff --git a/doc/userguide/index.rst b/doc/userguide/index.rst
@@ -0,0 +1,21 @@
+##########################
+  User Guide
+##########################
+
+.. toctree::
+   :maxdepth: 3
+   :hidden:
+
+   feature_detection_output
+   threshold_detection_parameters
+   feature_detection/index
+   segmentation_output
+   segmentation_parameters
+   tracking_output
+   bulk_statistics/index
+   transform_segmentation
+   big_datasets
+   features_without_segmented_area
+   publications
+   analysis
+