Merge branch 'main' into 86-include-mc-methods

.gitignore

@@ -1,3 +1,6 @@
+# Custom
+**/reference/api
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

.readthedocs.yaml

@@ -0,0 +1,35 @@
+# .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.10"
+        # 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/source/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:
+        - method: pip
+          path: .
+          extra_requirements:
+              - doc
+              - jupyter

README.md

@@ -1,6 +1,8 @@
-# catalog-tools
+# SeismoStats
 
-### Start developing:
+Measure your seismicity with **SeismoStats**, a Python package for seismicity analysis.
+
+## Start developing:
 
 ```
 # just use a basic virtual environment
@@ -19,24 +21,24 @@ pip install -e '.[dev]'
 tox
 ```
 
-### Use this repository inside another environment/code
+## Use this repository inside another environment/code
 
 ```
 # use it locally, being able to switch back and forth doing changes
 # enter this in your other environment
 pip install -e ../path/to/catalog-tools
 
 # if you don't need to do live changes in catalog-tools you can install it "from source"
-pip install git+https://github.com/swiss-seismological-service/catalog-tools.git
+pip install git+https://github.com/swiss-seismological-service/SeismoStats.git
 
 # if you want to install a specific branch:
-pip install git+https://github.com/swiss-seismological-service/catalog-tools.git@feature/branch
+pip install git+https://github.com/swiss-seismological-service/SeismoStats.git@feature/branch
 
 # update it once the repo has changed:
-pip install --force-reinstall git+https://github.com/swiss-seismological-service/catalog-tools.git
+pip install --force-reinstall git+https://github.com/swiss-seismological-service/SeismoStats.git
 ```
 
-### Problems with geos
+## Problems with geos
 
 ```
 1. geos_c.h not found

docs/Makefile

@@ -0,0 +1,26 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+server:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) --watch "../seismostats"
+
+clean:
+	rm -rf $(BUILDDIR)/

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/_templates/autosummary/class.rst

@@ -0,0 +1,32 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {% if item in members and not item.startswith('_') and not item in inherited_members%}
+        ~{{ name }}.{{ item }}
+      {% endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      {% if item in members and (not item.startswith('_') or item in ['__call__']) and not item in inherited_members %}
+        ~{{ name }}.{{ item }}
+      {% endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/source/conf.py

@@ -0,0 +1,51 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'SeismoStats'
+copyright = '2024, multiple'
+author = 'multiple'
+release = '0.1'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'myst_parser',
+    'sphinx.ext.autosectionlabel',
+    'nbsphinx',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.napoleon',
+    'nbsphinx_link'
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+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",
+}

docs/source/index.md

@@ -0,0 +1,19 @@
+```{toctree}
+:hidden:
+
+User Guide <user/index>
+API reference <reference/index>
+```
+
+# Seismo Stats
+
+Measure your seismicity with **SeismoStats**, a Python package for seismicity analysis.
+
+Check out the {doc}`user/usage` section for further information, or the {doc}`reference/index` for a technical reference.
+
+
+<!-- ## Indices and tables
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search` -->

docs/source/notebooks/catalog_Tools.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../notebooks/catalog_Tools.ipynb"
+}

docs/source/notebooks/catalog_examples.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../notebooks/catalog_examples.ipynb"
+}

docs/source/reference/catalog.md

@@ -0,0 +1,23 @@
+# Catalog
+
+```{eval-rst}
+.. currentmodule:: seismostats
+```
+
+## Constructor
+
+```{eval-rst}
+.. autosummary::
+    :toctree: api/
+
+    Catalog
+```
+
+## Transformation
+
+```{eval-rst}
+.. autosummary::
+    :toctree: api/
+
+    Catalog.bin_magnitudes
+```

docs/source/reference/index.md

@@ -0,0 +1,7 @@
+# API Documentation
+
+```{toctree}
+:maxdepth: 2
+
+catalog
+```

docs/source/user/docs.md

@@ -0,0 +1,17 @@
+# Adding Documentation
+
+## Building the Documentation
+1. Install the project including documentation dependencies using `pip install -e .[doc]` from the root of the project.
+2. Go to the `/docs` directory and run `make <arg>`, depending on your goal:
+    - `make html` to build the documentation.
+    - `make server` to build the documentation and start a local server on http://localhost:8000 to view the documentation and rebuild automatically.
+    - `make clean` to remove the built documentation.
+
+## Writing the Documentation
+Currently, the documentation has two main sections: The {doc}`index` which serves as a written tutorial for the project and the {doc}`../reference/index` which serves as a technical reference for the project.
+
+### The User Guide
+This is a written tutorial for the project. It should be written in a way that a new user can understand and use the project. Background on methods and concepts can and should be included.
+
+### The API Reference
+This is a technical reference for the project. The user can go and look up the specifics of a method or class, including specific examples. This is generated to a big extent from the docstrings in the code. The developer mostly just needs to decide on the structure of this part of the documentation, and write the docstrings in the code accordingly.

docs/source/user/examples.md

@@ -0,0 +1,8 @@
+# Examples
+
+```{toctree}
+:maxdepth: 1
+
+../notebooks/catalog_examples.nblink
+../notebooks/catalog_Tools.nblink
+```

docs/source/user/index.md

@@ -0,0 +1,9 @@
+# User Guide
+
+```{toctree}
+:maxdepth: 2
+
+usage
+docs
+examples
+```

docs/source/user/usage.md

@@ -0,0 +1,5 @@
+# Usage
+
+```{include} ../../../README.md
+:relative-images:
+```