Skip to content

Commit 671b54c

Browse files
schmidnischmidni
committed
docs: add sphinx api documentation
1 parent 3cce6dd commit 671b54c

File tree

15 files changed

+363
-1
lines changed

15 files changed

+363
-1
lines changed

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ node_modules/
44
dist/
55
test.py
66
ATLS_visualisation_concept.ipynb
7+
docs/*/api/
8+
docs/source/changelog.md
79

810
# Byte-compiled / optimized / DLL files
911
__pycache__/

‎CHANGELOG.md‎

Whitespace-only changes.

‎docs/Makefile‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
21+
22+
server:
23+
sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) --watch "../hermes_client" --re-ignore "api/.*" --re-ignore "changelog.md"
24+
25+
clean:
26+
rm -rf $(BUILDDIR)/ && rm -rf "$(SOURCEDIR)/reference/api"

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/source/_static/.gitkeep‎

Whitespace-only changes.

‎docs/source/_templates/autosummary/base.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{{ fullname.replace("seismostats.", "") | escape | underline}}
2+
3+
.. currentmodule:: {{ module }}
4+
5+
.. auto{{ objtype }}:: {{ objname }}

‎docs/source/_templates/autosummary/class.rst‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{{ fullname.replace("seismostats.", "") | escape | underline}}
2+
3+
.. currentmodule:: {{ module }}
4+
5+
.. autoclass:: {{ objname }}
6+
7+
8+
{% block attributes %}
9+
10+
{% if attributes %}
11+
.. rubric:: {{ _('Attributes') }}
12+
13+
.. autosummary::
14+
:toctree: ../api/
15+
:nosignatures:
16+
{% for item in attributes %}
17+
{% if item in members and not item.startswith('_') %}
18+
{% if (item in inherited_members and objname not in skip_inheritance) or item not in inherited_members %}
19+
~{{ name }}.{{ item }}
20+
{% endif %}
21+
{% endif %}
22+
{%- endfor %}
23+
{% endif %}
24+
{% endblock %}
25+
26+
{% block methods %}
27+
{% if methods %}
28+
.. rubric:: {{ _('Methods') }}
29+
30+
.. autosummary::
31+
:toctree: ../api/
32+
:nosignatures:
33+
{% for item in members %}
34+
{% if (item in methods or item in ['__call__']) and item not in ['__init__'] %}
35+
{% if (item in inherited_members and objname not in skip_inheritance) or item not in inherited_members %}
36+
~{{ name }}.{{ item }}
37+
{% endif %}
38+
{% endif %}
39+
{%- endfor %}
40+
{% endif %}
41+
{% endblock %}

‎docs/source/_templates/autosummary/module.rst‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
{{ fullname | escape | underline}}
2+
3+
.. automodule:: {{ fullname }}
4+
5+
{% block attributes %}
6+
{% if attributes %}
7+
.. rubric:: {{ _('Module Attributes') }}
8+
9+
.. autosummary::
10+
{% for item in attributes %}
11+
{{ item }}
12+
{%- endfor %}
13+
{% endif %}
14+
{% endblock %}
15+
16+
{% block functions %}
17+
{% if functions %}
18+
.. rubric:: {{ _('Functions') }}
19+
20+
.. autosummary::
21+
{% for item in functions %}
22+
{{ item }}
23+
{%- endfor %}
24+
{% endif %}
25+
{% endblock %}
26+
27+
{% block classes %}
28+
{% if classes %}
29+
.. rubric:: {{ _('Classes') }}
30+
31+
.. autosummary::
32+
{% for item in classes %}
33+
{{ item }}
34+
{%- endfor %}
35+
{% endif %}
36+
{% endblock %}
37+
38+
{% block exceptions %}
39+
{% if exceptions %}
40+
.. rubric:: {{ _('Exceptions') }}
41+
42+
.. autosummary::
43+
{% for item in exceptions %}
44+
{{ item }}
45+
{%- endfor %}
46+
{% endif %}
47+
{% endblock %}
48+
49+
{% block modules %}
50+
{% if modules %}
51+
.. rubric:: Modules
52+
53+
.. autosummary::
54+
:toctree:
55+
:recursive:
56+
{% for item in modules %}
57+
{{ item }}
58+
{%- endfor %}
59+
{% endif %}
60+
{% endblock %}

‎docs/source/conf.py‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
import os
7+
import shutil
8+
9+
import setuptools_scm
10+
11+
# -- Copy over changelog ------------------------------------------------------
12+
# Path to the project's root CHANGELOG.md
13+
changelog_src = os.path.abspath("../../CHANGELOG.md")
14+
changelog_dst = os.path.abspath("./changelog.md")
15+
16+
# Copy CHANGELOG.md into the docs folder
17+
if os.path.exists(changelog_src):
18+
shutil.copy(changelog_src, changelog_dst)
19+
20+
# -- Project information -----------------------------------------------------
21+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
22+
23+
project = 'hermes-client'
24+
copyright = '2025, multiple'
25+
author = 'multiple'
26+
version = setuptools_scm.get_version(root='../..',
27+
relative_to=__file__)
28+
release = setuptools_scm.get_version(root='../..',
29+
relative_to=__file__,
30+
version_scheme="python-simplified-semver",
31+
local_scheme="no-local-version")
32+
33+
# -- General configuration ---------------------------------------------------
34+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
35+
36+
extensions = [
37+
'myst_parser',
38+
'sphinx.ext.autosectionlabel',
39+
'sphinx.ext.autodoc',
40+
'sphinx.ext.autosummary',
41+
'sphinx.ext.intersphinx',
42+
'sphinx.ext.napoleon'
43+
]
44+
myst_enable_extensions = ["dollarmath", "amsmath"]
45+
myst_dmath_allow_labels = True
46+
autosectionlabel_prefix_document = True
47+
48+
templates_path = ['_templates']
49+
exclude_patterns = []
50+
napoleon_custom_sections = [('Returns', 'params_style')]
51+
52+
# allows to link to other projects :class:`pandas.DataFrame`
53+
intersphinx_mapping = {
54+
"pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
55+
}
56+
57+
autosummary_context = { # this is available in the template
58+
'skip_inheritance': [
59+
# 'Catalog',
60+
# 'ForecastCatalog',
61+
# 'GRRateGrid',
62+
# 'ForecastGRRateGrid',
63+
# 'CoordinateTransformer'
64+
]
65+
}
66+
autosummary_generate = True
67+
autosummary_generate_overwrite = True
68+
autodoc_default_options = {}
69+
70+
# -- Options for HTML output -------------------------------------------------
71+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
72+
73+
74+
html_theme = 'pydata_sphinx_theme'
75+
html_static_path = ['_static']
76+
html_theme_options = {
77+
"use_edit_page_button": False,
78+
"icon_links": [
79+
{
80+
"name": "GitHub",
81+
"url":
82+
"https://github.com/swiss-seismological-service/hermes-client",
83+
"icon": "fa-brands fa-square-github",
84+
"type": "fontawesome",
85+
}
86+
],
87+
# "navigation_depth": 3,
88+
}
89+
html_show_sourcelink = False
90+
navigation_with_keys = True
91+
html_context = {
92+
"default_mode": "light",
93+
}
94+
95+
96+
suppress_warnings = ['autosectionlabel.*',
97+
'myst.header',
98+
'config.cache']

‎docs/source/index.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
```{toctree}
2+
:hidden:
3+
4+
API reference <reference/index>
5+
Changelog <changelog>
6+
```
7+
8+
# hermes-client
9+
10+
Easily access data from the RT-HERMES API using Python.
11+
12+
Check {doc}`reference/index` section for a technical reference.
13+
14+
<!-- ## Indices and tables
15+
16+
- {ref}`genindex`
17+
- {ref}`modindex`
18+
- {ref}`search` -->

0 commit comments

Comments
 (0)