From 84ad67ad88bf848a4749aab5345dc93dd9822de2 Mon Sep 17 00:00:00 2001
From: Nicolas Schmid <nicolas@breiten.ch>
Date: Tue, 20 Feb 2024 14:57:20 +0100
Subject: [PATCH] feat: configure make, readthedocs

---
 .readthedocs.yaml                 | 31 +++++++++++++++++++++++++++++++
 docs/Makefile                     |  2 +-
 docs/source/conf.py               | 16 ++++++++++++++++
 docs/source/index.md              |  9 ++++-----
 docs/source/user/docs.md          |  2 +-
 docs/source/user/usage.md         | 24 +++---------------------
 seismostats/seismicity/catalog.py | 28 +++++++++++++++++++++++++---
 7 files changed, 81 insertions(+), 31 deletions(-)
 create mode 100644 .readthedocs.yaml

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 00000000..e423697c
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,31 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+    os: ubuntu-22.04
+    tools:
+        python: "3.12"
+        # You can also specify other tool versions:
+        # nodejs: "19"
+        # rust: "1.64"
+        # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+    configuration: docs/conf.py
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt
diff --git a/docs/Makefile b/docs/Makefile
index bf7f4b09..3b815202 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -20,7 +20,7 @@ help:
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 server:
-	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) --watch "../seismostats"
 
 clean:
 	rm -rf $(BUILDDIR)/
\ No newline at end of file
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 41a2ddde..f6a2b494 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -33,3 +33,19 @@
 
 html_theme = 'pydata_sphinx_theme'
 html_static_path = ['_static']
+html_theme_options = {
+    "use_edit_page_button": False,
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/swiss-seismological-service/SeismoStats",
+            "icon": "fa-brands fa-square-github",
+            "type": "fontawesome",
+        }
+    ]
+}
+html_show_sourcelink = False
+navigation_with_keys = True
+html_context = {
+    "default_mode": "light",
+}
diff --git a/docs/source/index.md b/docs/source/index.md
index fb20ea04..86cb9d77 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -5,12 +5,11 @@ User Guide <user/index>
 API reference <reference/index>
 ```
 
-```{include} ../../README.md
-:relative-images:
-```
+# Seismo Stats
+
+Measure your seismicity with **SeismoStats**, a Python package for seismicity analysis.
 
-Check out the {doc}`user/usage` section for further information, including how to
-{ref}`install <installation>` the project.
+Check out the {doc}`user/usage` section for further information, or the {doc}`reference/index` for a technical reference.
 
 
 <!-- ## Indices and tables
diff --git a/docs/source/user/docs.md b/docs/source/user/docs.md
index e457f58c..eab6aa0e 100644
--- a/docs/source/user/docs.md
+++ b/docs/source/user/docs.md
@@ -1,4 +1,4 @@
-# Creating and Building the Documentation
+# Adding Documentation
 
 ## Building the Documentation
 1. Install the project including documentation dependencies using `pip install -e .[doc]` from the root of the project.
diff --git a/docs/source/user/usage.md b/docs/source/user/usage.md
index 64470f58..61cc119d 100644
--- a/docs/source/user/usage.md
+++ b/docs/source/user/usage.md
@@ -1,23 +1,5 @@
 # Usage
 
-## Installation
-
-```bash
-pip install -e .
-python3 -m venv env
-
-# activate it
-source env/bin/activate
-
-# update build tools
-pip install -U pip wheel setuptools
-
-# install this package + requirements + development requirements ([dev])
-pip install -e '.[dev]'
-
-# run tests
-tox
-```
-
-## Code
-You can use the {py:func}`seismostats.Catalog` class to load a catalog.
\ No newline at end of file
+```{include} ../../../README.md
+:relative-images:
+```
\ No newline at end of file
diff --git a/seismostats/seismicity/catalog.py b/seismostats/seismicity/catalog.py
index d846068f..546b1a4e 100644
--- a/seismostats/seismicity/catalog.py
+++ b/seismostats/seismicity/catalog.py
@@ -39,14 +39,36 @@ class Catalog(pd.DataFrame):
             Data to initialize the catalog with.
         name : str, optional
             Name of the catalog.
-        args, kwargs : optional
-            Additional arguments and keyword arguments to pass to pandas
+        args : optional
+            Additional arguments to pass to pandas
+            DataFrame constructor.
+        kwargs: optional
+            Additional keyword arguments to pass to pandas
             DataFrame constructor.
-
     Notes:
         The Catalog class is a subclass of pandas DataFrame, and inherits
         all of its methods and attributes.
+
+    Examples:
+        Create a Catalog from a dictionary.
+
+        >>> import pandas as pd
+        >>> from seismostats.seismicity import Catalog
+        >>> data = {'longitude': [0, 1, 2],
+        ...         'latitude': [0, 1, 2],
+        ...         'depth': [0, 1, 2],
+        ...         'time': pd.to_datetime(['2021-01-01 00:00:00',
+        ...                                 '2021-01-01 00:00:00',
+        ...                                 '2021-01-01 00:00:00']),
+        ...         'magnitude': [1, 2, 3]}
+        >>> catalog = Catalog(data)
+        >>> catalog
+           longitude  latitude  depth                time  magnitude
+        0          0         0      0 2021-01-01 00:00:00          1
+        1          1         1      1 2021-01-01 00:00:00          2
+        2          2         2      2 2021-01-01 00:00:00          3
     """
+
     _metadata = ['name', '_required_cols']
     _required_cols = REQUIRED_COLS_CATALOG