Huracan-project · stella-bourdin · Jan 9, 2025 · Nov 25, 2024 · Nov 25, 2024 · Nov 25, 2024
diff --git a/.gitignore b/.gitignore
@@ -43,3 +43,6 @@ docs/_build/
 
 # Sphinx autosummary folder
 docs/api/_autosummary/
+
+# Powerpoint checkpoints
+*~$*
diff --git a/README.md b/README.md
@@ -1,110 +1,10 @@
 # huracanpy
 [![Documentation Status](https://readthedocs.org/projects/huracanpy/badge/?version=latest)](https://huracanpy.readthedocs.io/en/latest/?badge=latest)
 
-A python package for working with various forms of feature tracking data
+A python package for working with various forms of feature tracking data.
+Click the badge above for the documentation.
 
-## Version 1 coming soon! Subscribe for notification.
-We will release version 1 soon (by the end of November 2024). We advice you wait for this version to install the package. To stay updated about it, there are two options:
-1. Most specific: Subscribe to [this discussion](https://github.com/Huracan-project/huracanpy/discussions/57), that we will use to communicate with our community of users.
+## Version 1 released! Subscribe for updates.
+1. Most specific: Subscribe to [this discussion](https://github.com/Huracan-project/huracanpy/discussions/57) for further updates.
 2. Less specific: "Watch" the repo by clicking the button on the top-right of this page. Select "custom" then tick "discussions". You can always go back if there turns out to be too much emails. 
 (We wish there was a better way for you to subscribe to announcements. If you agree with us, please up [this issue](https://github.com/orgs/community/discussions/3951).)
-
-## Installation
-To install the package, you can use `pip`: `pip install huracanpy`.
-
-This can fail with older python versions due to issues with installing cartopy through
-pip. If this happens, use conda to install cartopy first
-(e.g. `conda install -c conda-forge cartopy`), then install huracanpy as normal
-
-
-## Usage
-The idea of this package is to be a standard way for working with cyclone track data. We
-were all working on track data, but in slightly different ways which makes sharing code
-more difficult. The method chosen here is to treat a set of tracks as an xarray
-[Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html) with a
-minimal number of assumed variables (track_id, lon, lat, time). e.g. running
-
-```python
-import huracanpy
-
-tracks = huracanpy.load(huracanpy.example_csv_file)
-minimal_tracks = tracks[["track_id", "lon", "lat", "time"]]
-
-print(minimal_tracks)
-```
-gives
-```
-<xarray.Dataset>
-Dimensions:   (obs: 99)
-Coordinates:
-  * obs       (obs) int64 0 1 2 3 4 5 6 7 8 9 ... 89 90 91 92 93 94 95 96 97 98
-Data variables:
-    track_id  (obs) int64 0 0 0 0 0 0 0 0 0 0 0 0 0 ... 2 2 2 2 2 2 2 2 2 2 2 2
-    lon       (obs) float64 120.5 119.0 119.0 119.2 ... 57.5 58.5 60.25 62.25
-    lat       (obs) float64 -14.25 -14.75 -15.0 -15.0 ... -39.25 -42.0 -45.5
-    time      (obs) datetime64[ns] 1980-01-06T06:00:00 ... 1980-01-30T18:00:00
-```
-
-where each "obs" corresponds to a TC point (time, lon, lat).
-All variables that were present in your file are variables in the loaded dataset.
-
-Note that the data is one dimensional but represents multiple tracks. This is done
-rather than having track_id as an additional dimension to avoid having to add a bunch of
-extra blank data to each track when they are not the same length. The `groupby` function
-allows us to easily loop over or index tracks in this format.
-```python
-import huracanpy
-
-tracks = huracanpy.load(huracanpy.example_csv_file)
-
-track_groups = tracks.groupby("track_id")
-
-# Selecting track by ID
-# The track_id is not necessarily an integer, it follows whatever you have loaded
-# e.g. could be a string for IBTrACS
-track_id1 = track_groups[1]
-
-# Iterating over all tracks
-# Each track will be a subset of the xarray Dataset with a unique track_id
-for n, track in track_groups:
-    # Do something with the track
-```
-
-#### csv tracks data
-If you tracks are stored in csv (including if they were outputed from TempestExtremes' StitchNodes),
-you can specify the `tracker="csv"` argument, or, if your filename ends with `csv`, it will be detected automatically.
-
-#### TRACK tracks data
-If your tracks are in TRACK format, use the `tracker="TRACK"` option
-
-## Contributing
-We welcome suggestions and contributions to huracanpy. If you have existing code for
-working with track data, we would definitely welcome contributions/suggestions for
-modifying it to work with the xarray format used here. To add suggestions, feel free to
-open an issue or contact us. To contribute code, please make a fork of this repository,
-follow the instructions below, and open a pull request.
-
-To install your copy locally run
-```shell
-pip install -e .[dev]
-```
-The "[dev]" argument installs the following optional packages that are useful for
-contributing to development
-1. **pytest**
-
-    We use [pytest](https://docs.pytest.org/en/latest/) to run automated tests. If you
-    add a new feature, it would be good to also add tests to check that feature is
-    working and keeps working in the future. You can also run `pytest` from the top
-    level directory of the package to check that your changes haven't broken anything.
-2. **ruff**
-
-    We use [ruff](https://docs.astral.sh/ruff/) to automatically keep the style of the
-    code consistent so we don't have to worry about it. To check that your code passes
-    you can run `ruff check` and `ruff format --check`. To automatically fix differences
-    run `ruff check --fix` and `ruff format`.
-
-3. **pre-commit**
-
-    You can use [pre-commit](https://pre-commit.com/) to automate the formatting done by
-    ruff. After running `pre-commit install` at the top level directory, any future git
-    commits will automatically run the ruff formatting on any files you have changes.
diff --git a/docs/api/assess.rst b/docs/api/assess.rst
@@ -1,3 +1,5 @@
+.. _api-assess:
+
 assess
 ======
 

diff --git a/docs/api/calc.rst b/docs/api/calc.rst
@@ -1,3 +1,5 @@
+.. _api-calc:
+
 calc
 ====
 

diff --git a/docs/api/huracanpy.rst b/docs/api/huracanpy.rst
@@ -1,3 +1,5 @@
+.. _api-core:
+
 huracanpy
 =========
 

diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -1,3 +1,5 @@
+.. _api-index:
+
 API
 ===
 

diff --git a/docs/api/info.rst b/docs/api/info.rst
@@ -1,3 +1,5 @@
+.. _api-info:
+
 info
 ====
 

diff --git a/docs/api/plot.rst b/docs/api/plot.rst
@@ -1,3 +1,5 @@
+.. _api-plot:
+
 plot
 ====
 

diff --git a/docs/api/tc.rst b/docs/api/tc.rst
@@ -1,3 +1,5 @@
+.. _api-tc:
+
 tc
 ==
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -21,6 +21,7 @@
     "nbsphinx",
     "sphinx_copybutton",
     "sphinx_design",
+    "myst_parser",
 ]
 
 templates_path = ["_templates"]
@@ -43,10 +44,21 @@
     "metpy": ("https://unidata.github.io/MetPy/latest/", None),
 }
 
+# myst parser (markdown)
+myst_enable_extensions = [
+    "colon_fence",
+]
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "pydata_sphinx_theme"
-html_theme_options = {"github_url": "https://github.com/Huracan-project/huracanpy"}
+html_theme_options = {
+    "github_url": "https://github.com/Huracan-project/huracanpy",
+    "show_toc_level": 3,
+    "logo_only": True,
+    "display_version": False,
+}
 html_static_path = ["_static"]
+html_logo = "images/logo/logo-with-name/Slide1.png"
 html_css_files = ["css/custom.css"]
diff --git a/docs/dev_guide/changelog.md b/docs/dev_guide/changelog.md
@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## v1.1.0 (unreleased)
+### Added
+- Support for WiTRACK text files in huracanpy.load
+
+## v1.0.0
+### Added
+- xarray Dataset accessor (`hrcn`)
+- Extra keyword arguments to `huracanpy.load`
+  - `rename`
+  - `units`
+  - `baselon`
+- `sel_id` function to select a single track by track_id from a `Dataset` but faster than using `groupby`
+
+### Changed
+- Simplified module namespaces
+  - `utils.{module}.{function}` -> `info.{function}`
+  - `diags.{module}.{function}` -> `calc.{function}` or `tc.{function}`
+  - `subset.trackswhere` -> `trackswhere`
+- Simplified function naming
+  - `plot_` prefix removed functions in `plot` module
+- Modified arguments to `load`
+  - keyword `tracker` renamed `source` to reflect not all tracks are from trackers, e.g. IBTrACS or statistical-dynamical downscaling models
+  - Use `ibtracs_subset` to determine whether the subset is online or not, removing `ibtracs_online` keyword
+  - When `filename` is specified for an online IBTrACS dataset, save the downloaded data to that file, rather than using `ibtracs_clean=False` and a default filename
+- Use a single matching function `assess.match` for 2 or more datasets instead of `assess.match_pair` and `assess.match_multiple`
+- Remove `get_` from functions in `info`. Instead this syntax is used to differentiate `get_` and `add_` functions in the `hrcn` accessor
+- Split `info.get_land_or_ocean` into `is_land` and `is_ocean`
+- Renamed `tc.sshs_cat` to `tc.saffir_simpson_category` and `tc.pres_cat` to `tc.pressure_category`
+- Improved support for calculations with units (using metpy style functions)
+- Updated IBTrACS data
+
+### Removed
+- `add_info` argument from `huracanpy.load`
+- `add_all_info` function. Instead use `add_` functions on `hrcn` accessor
+- `get_time`. Functionality already covered by `pandas.to_datetime`
+
+### Fixed
+- `huracanpy.info.season` now works with `cftime.datetime`
diff --git a/docs/dev_guide/doc.md b/docs/dev_guide/doc.md
@@ -0,0 +1,42 @@
+# Documentation
+
+## Docstrings
+The API documentation is built from docstrings written with the code.
+We use [numpy style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html) docstrings.
+If you are adding a function or class, give it a numpy-style docstring and add the name of the function/class to the relevant .rst file in `docs/api/`, and it will be included in the documentation.
+
+## Documentation webpages
+
+### Sphinx
+The present documentation is built with [sphinx](https://www.sphinx-doc.org/en/master/). If you installed `huracanPy` following the developers' instruction, you should have the following package installed in your environment:
+
+- `sphinx`
+- `pydata-sphinx-theme`
+- `nbsphinx`
+- `sphinx-copybutton`
+
+All documentations files are in the `docs` folder at the root of the package.
+They are either `.rst` (reStructured Text), `.md` (markdown), or `.ipynb` (Jupyter Notebook, which includes MarkDown) files.
+
+:::{hint}
+To build the documentation locally, run `make html` in this folder. This is useful to preview your changes before you commit them. 
+:::
+
+
+To learn how to use these tools, you may want to check out the following resources:
+- reStructuredText
+  - [Wikipedia page](https://en.wikipedia.org/wiki/ReStructuredText)
+  - [Sphinx tutorial](https://sphinx-tutorial.readthedocs.io/step-1/)
+  - [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html)
+- Jupyter notebooks
+  - [Jupyter website](https://jupyter.org/)
+- Markdown
+  - [Jupyter doc](https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Working%20With%20Markdown%20Cells.html)
+  - [Markdown Guide](https://www.markdownguide.org/)
+  - [Markdown tutorial](https://www.markdowntutorial.com/)
+  - [MyST doc](https://myst-parser.readthedocs.io/en/stable/)
+- Sphinx
+  - [Documentation](https://www.sphinx-doc.org/en/master/index.html)
+  - [Tutorial](https://sphinx-tutorial.readthedocs.io/)
+
+You can also check out the source code of documentation pages you like to find how to do a specific thing.
diff --git a/docs/dev_guide/doc.rst b/docs/dev_guide/doc.rst
diff --git a/docs/dev_guide/examples.rst → docs/dev_guide/examples.md b/docs/dev_guide/examples.rst → docs/dev_guide/examples.md
@@ -1,17 +1,16 @@
-==============================
-Adding examples to the gallery
-==============================
+# Adding examples to the gallery
 
 You have a cool application of HuracanPy? We would love for you to share it with the world to showcase what can be done with the package!
 
 The recommend format for example pages in Jupyter Notebooks. While it is preferable that examples are based on HuracanPy's embedded example data, on downloadable data, or on data that is generated within the example, it is possible to use your own data. In that case, the notebook cannot be updated when the documentation is re-built (see NB below).
 
-1. Create a notebook with your code in docs/examples/, some explanations, and your potential nice images.
-2. Flag a thumbnail image (if any) with [TODO]
-3. (Optionnal) Check out the result by building the doc locally.
+1. Create a notebook with your code in `docs/examples/`, some explanations, and your potential nice images.
+2. By default the thumbnail image in the gallery will be the last image. To use a different image, add `nbsphinx-thumbnail` to the tags of the cell you want to use. See [here](https://nbsphinx.readthedocs.io/en/latest/gallery/cell-tag.html) for more details.
+3. (Optional) Check out the result by building the doc locally. Run `make html` in the `docs` folder and open the html files in `docs/_build/html/`
 4. Commit and push the changes to your own fork.
 5. Create a pull request to add your example to the online documentation. 
 
-NB: Notebooks may or may not be re-run at each documentation build. While re-running helps with keeping the documentation up-to-date, we cannot re-run your notebook if it uses data that is on your own computer. We also do not wish to re-run computations that may take significant time every time. 
+NB: Notebooks may or may not be re-run at each documentation build. While re-running helps with keeping the documentation up-to-date, we cannot re-run your notebook if it uses data that is on your own computer. We also do not wish to re-run computations that may take significant time every time.
+
 * For your notebook to be re-run, you need to clear cell's output: In the Edit Menu, select "Clear Outputs of All Cells" before saving your notebook. 
 * For your notebook *not* to be re-run, do the opposite: Be careful to run all cells before saving the notebook. 
diff --git a/docs/dev_guide/index.rst b/docs/dev_guide/index.rst
@@ -15,16 +15,12 @@ Contributor's Guide
 
 It is important that you know the basics of Git to contribute. [LINK]
 
-1. Set up your environment and install the package with developer's options. [LINK]
-2. 
-
-    * If you do not have a specific change in mind, check out the `GitHub issues <https://github.com/Huracan-project/huracanpy/issues>`_, or contact the developers [LINK]. 
-    * If you already do, move on to the next step.
-
+1. Set up your environment and install the package with developer's options. [:doc:`link <setup>`]
+2. If you do not have a specific change in mind, check out the `GitHub issues <https://github.com/Huracan-project/huracanpy/issues>`_, or contact the developers [LINK]. If you already do, move on to the next step.
 3. Identify the sources files that require modification, and go ahead with implementing what you need. Remember to commit regularly your changes.
-4. Implement relevant test. [LINK]
-5. Update or create relevant documentation. [LINK]
-6. Create a pull request for your contribution. 
+4. Implement relevant test. [:doc:`link <tests>`]
+5. Update or create relevant documentation. [:doc:`link <doc>`]
+6. Create a pull request for your contribution. [`Github <https://github.com/Huracan-project/huracanpy/pulls>`_]
 
 If you know what it means, and think it is relevant, think about implementing your function in the `hrcn` accessor as well. 
 
@@ -35,7 +31,9 @@ Alternatively, if you think you have something useful to contribute like a funct
     :maxdepth: 3
     :hidden:
 
+    self
     setup
     examples
     doc
-    tests
+    tests
+    changelog
-Original file line number
+Diff line change
@@ -1,3 +1,5 @@
+    .. _api-assess:
     assess
     ======
@@ Expand Down @@