From 18804c24e97990f95f322e0c7e5e9d5f61fd1ad2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20M=C3=BCller?= Date: Wed, 19 Oct 2022 15:13:46 +0200 Subject: [PATCH 1/5] tools: add documentation of EARTH_RADIUS --- docs/source/tools.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/tools.rst b/docs/source/tools.rst index e3e91643..c39b396b 100644 --- a/docs/source/tools.rst +++ b/docs/source/tools.rst @@ -2,6 +2,7 @@ gstools.tools ============= .. automodule:: gstools.tools + :members: EARTH_RADIUS .. raw:: latex From fbc6e6b0a043cf8574c1a303fdc666b1edc62d84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20M=C3=BCller?= Date: Wed, 19 Oct 2022 15:14:27 +0200 Subject: [PATCH 2/5] doc: keep 'Other Parameters' section; better align properties in html --- docs/source/_static/custom.css | 3 +++ docs/source/conf.py | 13 ++++++++++--- 2 files changed, 13 insertions(+), 3 deletions(-) create mode 100644 docs/source/_static/custom.css diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 00000000..e02ca17a --- /dev/null +++ b/docs/source/_static/custom.css @@ -0,0 +1,3 @@ +dl.py.property { + display: block !important; +} diff --git a/docs/source/conf.py b/docs/source/conf.py index e1bbbe08..2c8a627c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -83,7 +83,10 @@ def setup(app): # Notes in boxes napoleon_use_admonition_for_notes = True # Attributes like parameters -# napoleon_use_ivar = True +napoleon_use_ivar = True +# keep "Other Parameters" section +# https://github.com/sphinx-doc/sphinx/issues/10330 +napoleon_use_param = False # this is a nice class-doc layout numpydoc_show_class_members = True # class members have no separate file, so they are not in a toctree @@ -125,7 +128,7 @@ def setup(app): # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = "en" # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -164,7 +167,11 @@ def setup(app): # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ['_static'] +html_static_path = ["_static"] + +# These paths are either relative to html_static_path +# or fully qualified paths (eg. https://...) +html_css_files = ["custom.css"] # Custom sidebar templates, must be a dictionary that maps document names # to template names. From cbe2027531410d3ff1f8225200ed3d14f7cba5e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20M=C3=BCller?= Date: Sat, 22 Oct 2022 17:36:39 +0200 Subject: [PATCH 3/5] doc: autogenerate toctree for autosummary; add EARTH_RADIUS; better reference covmodel.plot --- src/gstools/__init__.py | 3 ++- src/gstools/covmodel/__init__.py | 4 +++- src/gstools/covmodel/base.py | 2 +- src/gstools/covmodel/plot.py | 2 ++ src/gstools/field/__init__.py | 2 ++ src/gstools/field/generator.py | 2 ++ src/gstools/field/upscaling.py | 2 ++ src/gstools/tools/__init__.py | 2 ++ 8 files changed, 16 insertions(+), 3 deletions(-) diff --git a/src/gstools/__init__.py b/src/gstools/__init__.py index 2d0e7232..e4870090 100644 --- a/src/gstools/__init__.py +++ b/src/gstools/__init__.py @@ -14,6 +14,8 @@ =========== .. autosummary:: + :toctree: generated + covmodel field variogram @@ -123,7 +125,6 @@ .. autosummary:: EARTH_RADIUS - """ # Hooray! from gstools import ( diff --git a/src/gstools/covmodel/__init__.py b/src/gstools/covmodel/__init__.py index a793ae6a..6fcdcdab 100644 --- a/src/gstools/covmodel/__init__.py +++ b/src/gstools/covmodel/__init__.py @@ -8,7 +8,9 @@ ^^^^^^^^^^^ .. autosummary:: - plot + :toctree: generated + + plot Covariance Base-Class ^^^^^^^^^^^^^^^^^^^^^ diff --git a/src/gstools/covmodel/base.py b/src/gstools/covmodel/base.py index 8d71e1ad..2e366f94 100644 --- a/src/gstools/covmodel/base.py +++ b/src/gstools/covmodel/base.py @@ -310,7 +310,7 @@ def plot(self, func="variogram", **kwargs): # pragma: no cover **kwargs Keyword arguments forwarded to the plotting function - `"plot_" + func` in :any:`gstools.covmodel.plot`. + `"plot_" + func` in :py:mod:`gstools.covmodel.plot`. See Also -------- diff --git a/src/gstools/covmodel/plot.py b/src/gstools/covmodel/plot.py index 535c872f..574e0e20 100644 --- a/src/gstools/covmodel/plot.py +++ b/src/gstools/covmodel/plot.py @@ -7,6 +7,8 @@ The following classes and functions are provided .. autosummary:: + :toctree: generated + plot_variogram plot_covariance plot_correlation diff --git a/src/gstools/field/__init__.py b/src/gstools/field/__init__.py index 52e40983..aa51bef4 100644 --- a/src/gstools/field/__init__.py +++ b/src/gstools/field/__init__.py @@ -8,6 +8,8 @@ ^^^^^^^^^^^ .. autosummary:: + :toctree: generated + generator upscaling diff --git a/src/gstools/field/generator.py b/src/gstools/field/generator.py index 60e327b3..c2de58ff 100644 --- a/src/gstools/field/generator.py +++ b/src/gstools/field/generator.py @@ -7,6 +7,8 @@ The following classes are provided .. autosummary:: + :toctree: generated + Generator RandMeth IncomprRandMeth diff --git a/src/gstools/field/upscaling.py b/src/gstools/field/upscaling.py index bbcf12c7..cf77892d 100644 --- a/src/gstools/field/upscaling.py +++ b/src/gstools/field/upscaling.py @@ -7,6 +7,8 @@ The following functions are provided .. autosummary:: + :toctree: generated + var_coarse_graining var_no_scaling """ diff --git a/src/gstools/tools/__init__.py b/src/gstools/tools/__init__.py index ebf657e3..730026cf 100644 --- a/src/gstools/tools/__init__.py +++ b/src/gstools/tools/__init__.py @@ -61,6 +61,8 @@ EARTH_RADIUS ---- + +.. autodata:: EARTH_RADIUS """ from gstools.tools.export import ( From 212705d8f6e44790ca4b579adb32212f10c42b18 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20M=C3=BCller?= Date: Sat, 22 Oct 2022 17:37:14 +0200 Subject: [PATCH 4/5] docs: simpler api doc generation --- docs/source/_templates/autosummary/module.rst | 9 +++++++++ docs/source/conf.py | 2 +- docs/source/covmodel.plot.rst | 11 ----------- docs/source/covmodel.rst | 13 ------------- docs/source/field.generator.rst | 12 ------------ docs/source/field.rst | 14 -------------- docs/source/field.upscaling.rst | 10 ---------- docs/source/krige.rst | 8 -------- docs/source/normalizer.rst | 8 -------- docs/source/package.rst | 12 ------------ docs/source/random.rst | 8 -------- docs/source/tools.rst | 9 --------- docs/source/transform.rst | 8 -------- docs/source/variogram.rst | 8 -------- 14 files changed, 10 insertions(+), 122 deletions(-) create mode 100644 docs/source/_templates/autosummary/module.rst delete mode 100644 docs/source/covmodel.plot.rst delete mode 100644 docs/source/covmodel.rst delete mode 100644 docs/source/field.generator.rst delete mode 100644 docs/source/field.rst delete mode 100644 docs/source/field.upscaling.rst delete mode 100644 docs/source/krige.rst delete mode 100644 docs/source/normalizer.rst delete mode 100644 docs/source/random.rst delete mode 100644 docs/source/tools.rst delete mode 100644 docs/source/transform.rst delete mode 100644 docs/source/variogram.rst diff --git a/docs/source/_templates/autosummary/module.rst b/docs/source/_templates/autosummary/module.rst new file mode 100644 index 00000000..04aefe90 --- /dev/null +++ b/docs/source/_templates/autosummary/module.rst @@ -0,0 +1,9 @@ +{{ fullname | escape | underline}} + +.. currentmodule:: {{ fullname }} + +.. automodule:: {{ fullname }} + +.. raw:: latex + + \clearpage diff --git a/docs/source/conf.py b/docs/source/conf.py index 2c8a627c..f197f626 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -160,7 +160,7 @@ def setup(app): # Toc options "collapse_navigation": False, "sticky_navigation": True, - "navigation_depth": 4, + "navigation_depth": 6, "includehidden": True, "titles_only": False, } diff --git a/docs/source/covmodel.plot.rst b/docs/source/covmodel.plot.rst deleted file mode 100644 index 9e4e29b7..00000000 --- a/docs/source/covmodel.plot.rst +++ /dev/null @@ -1,11 +0,0 @@ -gstools.covmodel.plot ---------------------- - -.. automodule:: gstools.covmodel.plot - :members: - :undoc-members: - :show-inheritance: - -.. raw:: latex - - \clearpage diff --git a/docs/source/covmodel.rst b/docs/source/covmodel.rst deleted file mode 100644 index 74e7cebe..00000000 --- a/docs/source/covmodel.rst +++ /dev/null @@ -1,13 +0,0 @@ -gstools.covmodel -================ - -.. automodule:: gstools.covmodel - -.. raw:: latex - - \clearpage - -.. toctree:: - :hidden: - - covmodel.plot.rst diff --git a/docs/source/field.generator.rst b/docs/source/field.generator.rst deleted file mode 100644 index ee39aac1..00000000 --- a/docs/source/field.generator.rst +++ /dev/null @@ -1,12 +0,0 @@ -gstools.field.generator ------------------------ - -.. automodule:: gstools.field.generator - :members: - :undoc-members: - :inherited-members: - :show-inheritance: - -.. raw:: latex - - \clearpage diff --git a/docs/source/field.rst b/docs/source/field.rst deleted file mode 100644 index c37b4966..00000000 --- a/docs/source/field.rst +++ /dev/null @@ -1,14 +0,0 @@ -gstools.field -============= - -.. automodule:: gstools.field - -.. raw:: latex - - \clearpage - -.. toctree:: - :hidden: - - field.generator.rst - field.upscaling.rst diff --git a/docs/source/field.upscaling.rst b/docs/source/field.upscaling.rst deleted file mode 100644 index 2a7da282..00000000 --- a/docs/source/field.upscaling.rst +++ /dev/null @@ -1,10 +0,0 @@ -gstools.field.upscaling ------------------------ - -.. automodule:: gstools.field.upscaling - :members: - :undoc-members: - -.. raw:: latex - - \clearpage diff --git a/docs/source/krige.rst b/docs/source/krige.rst deleted file mode 100644 index e7eb6bd4..00000000 --- a/docs/source/krige.rst +++ /dev/null @@ -1,8 +0,0 @@ -gstools.krige -============= - -.. automodule:: gstools.krige - -.. raw:: latex - - \clearpage diff --git a/docs/source/normalizer.rst b/docs/source/normalizer.rst deleted file mode 100644 index 396c7cea..00000000 --- a/docs/source/normalizer.rst +++ /dev/null @@ -1,8 +0,0 @@ -gstools.normalizer -================== - -.. automodule:: gstools.normalizer - -.. raw:: latex - - \clearpage diff --git a/docs/source/package.rst b/docs/source/package.rst index 792fa973..fe12233b 100644 --- a/docs/source/package.rst +++ b/docs/source/package.rst @@ -7,15 +7,3 @@ GSTools API .. raw:: latex \clearpage - -.. toctree:: - :hidden: - - covmodel.rst - field.rst - variogram.rst - krige.rst - random.rst - tools.rst - transform.rst - normalizer.rst diff --git a/docs/source/random.rst b/docs/source/random.rst deleted file mode 100644 index c4331499..00000000 --- a/docs/source/random.rst +++ /dev/null @@ -1,8 +0,0 @@ -gstools.random -============== - -.. automodule:: gstools.random - -.. raw:: latex - - \clearpage diff --git a/docs/source/tools.rst b/docs/source/tools.rst deleted file mode 100644 index c39b396b..00000000 --- a/docs/source/tools.rst +++ /dev/null @@ -1,9 +0,0 @@ -gstools.tools -============= - -.. automodule:: gstools.tools - :members: EARTH_RADIUS - -.. raw:: latex - - \clearpage diff --git a/docs/source/transform.rst b/docs/source/transform.rst deleted file mode 100644 index a456cb12..00000000 --- a/docs/source/transform.rst +++ /dev/null @@ -1,8 +0,0 @@ -gstools.transform -================= - -.. automodule:: gstools.transform - -.. raw:: latex - - \clearpage diff --git a/docs/source/variogram.rst b/docs/source/variogram.rst deleted file mode 100644 index 2f50d266..00000000 --- a/docs/source/variogram.rst +++ /dev/null @@ -1,8 +0,0 @@ -gstools.variogram -================= - -.. automodule:: gstools.variogram - -.. raw:: latex - - \clearpage From b09664bb2befc0c74d238273ef75e4bf954e1560 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20M=C3=BCller?= Date: Thu, 27 Oct 2022 13:41:41 +0200 Subject: [PATCH 5/5] docs: fix links in sidebar --- docs/source/_templates/layout.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html index e2649c4b..54ceb56b 100644 --- a/docs/source/_templates/layout.html +++ b/docs/source/_templates/layout.html @@ -21,7 +21,7 @@

{% endblock %}