diff --git a/.gitignore b/.gitignore index 3702c4f..6e82817 100644 --- a/.gitignore +++ b/.gitignore @@ -116,7 +116,7 @@ src/ogs5py/_version.py # generated docs docs/source/examples/ -docs/source/generated/ +docs/source/api/ # other settings .vscode/ diff --git a/LICENSE b/LICENSE index 16a02ab..ed38ae8 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2019 Sebastian Mueller +Copyright (c) 2023 Sebastian Mueller Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 7ec42f4..e4b85c2 100644 --- a/README.md +++ b/README.md @@ -178,7 +178,7 @@ You can contact us via . ## License -[MIT][gpl_link] © 2018-2022 (inspired by Falk Hesse and Miao Jing) +[MIT][gpl_link] © 2018-2023 (inspired by Falk Hesse and Miao Jing) This project is based on [OGSPY][ogspy_link]. diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000..e02ca17 --- /dev/null +++ b/docs/source/_static/custom.css @@ -0,0 +1,3 @@ +dl.py.property { + display: block !important; +} diff --git a/docs/source/_templates/autosummary/module.rst b/docs/source/_templates/autosummary/module.rst new file mode 100644 index 0000000..04aefe9 --- /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/_templates/layout.html b/docs/source/_templates/layout.html index 368174e..863fcc5 100644 --- a/docs/source/_templates/layout.html +++ b/docs/source/_templates/layout.html @@ -21,7 +21,7 @@

{% endblock %} diff --git a/docs/source/package.rst b/docs/source/api.rst similarity index 54% rename from docs/source/package.rst rename to docs/source/api.rst index ff054eb..9471d45 100644 --- a/docs/source/package.rst +++ b/docs/source/api.rst @@ -7,10 +7,3 @@ ogs5py API .. raw:: latex \clearpage - -.. toctree:: - :hidden: - - fileclasses.rst - reader.rst - tools.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index 5ef5c6d..34743a2 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -49,7 +49,7 @@ def setup(app): "sphinx.ext.doctest", "sphinx.ext.intersphinx", "sphinx.ext.coverage", - "sphinx.ext.imgmath", + "sphinx.ext.mathjax", "sphinx.ext.ifconfig", "sphinx.ext.viewcode", "sphinx.ext.autosummary", @@ -69,7 +69,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 @@ -111,7 +114,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. @@ -143,14 +146,18 @@ def setup(app): # Toc options "collapse_navigation": False, "sticky_navigation": True, - "navigation_depth": 4, + "navigation_depth": 6, "includehidden": True, "titles_only": False, } # 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. @@ -236,11 +243,8 @@ def setup(app): # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { - "Python 3.6": ("https://docs.python.org/3.6", None), "Python": ("https://docs.python.org/", None), "NumPy": ("http://docs.scipy.org/doc/numpy/", None), "matplotlib": ("http://matplotlib.org", None), "Sphinx": ("http://www.sphinx-doc.org/en/stable/", None), - # "hankel": ("https://hankel.readthedocs.io/en/latest/", None), - # "emcee": ("http://dfm.io/emcee/current/", None), } diff --git a/docs/source/contents.rst b/docs/source/contents.rst index afd0d9b..24d389a 100644 --- a/docs/source/contents.rst +++ b/docs/source/contents.rst @@ -4,9 +4,9 @@ Contents .. toctree:: :includehidden: - :maxdepth: 3 + :maxdepth: 5 index tutorials - package + api changelog diff --git a/docs/source/fileclasses.base.rst b/docs/source/fileclasses.base.rst deleted file mode 100644 index bdff8c6..0000000 --- a/docs/source/fileclasses.base.rst +++ /dev/null @@ -1,8 +0,0 @@ -ogs5py.fileclasses.base -======================= - -.. automodule:: ogs5py.fileclasses.base - -.. raw:: latex - - \clearpage \ No newline at end of file diff --git a/docs/source/fileclasses.gli.generator.rst b/docs/source/fileclasses.gli.generator.rst deleted file mode 100644 index 5dc5ecf..0000000 --- a/docs/source/fileclasses.gli.generator.rst +++ /dev/null @@ -1,8 +0,0 @@ -ogs5py.fileclasses.gli.generator -================================ - -.. automodule:: ogs5py.fileclasses.gli.generator - -.. raw:: latex - - \clearpage diff --git a/docs/source/fileclasses.gli.rst b/docs/source/fileclasses.gli.rst deleted file mode 100644 index e9d3224..0000000 --- a/docs/source/fileclasses.gli.rst +++ /dev/null @@ -1,13 +0,0 @@ -ogs5py.fileclasses.gli -====================== - -.. automodule:: ogs5py.fileclasses.gli - -.. raw:: latex - - \clearpage - -.. toctree:: - :hidden: - - fileclasses.gli.generator.rst diff --git a/docs/source/fileclasses.msh.generator.rst b/docs/source/fileclasses.msh.generator.rst deleted file mode 100644 index 49a8563..0000000 --- a/docs/source/fileclasses.msh.generator.rst +++ /dev/null @@ -1,8 +0,0 @@ -ogs5py.fileclasses.msh.generator -================================ - -.. automodule:: ogs5py.fileclasses.msh.generator - -.. raw:: latex - - \clearpage diff --git a/docs/source/fileclasses.msh.rst b/docs/source/fileclasses.msh.rst deleted file mode 100644 index b7bd08f..0000000 --- a/docs/source/fileclasses.msh.rst +++ /dev/null @@ -1,13 +0,0 @@ -ogs5py.fileclasses.msh -====================== - -.. automodule:: ogs5py.fileclasses.msh - -.. raw:: latex - - \clearpage - -.. toctree:: - :hidden: - - fileclasses.msh.generator.rst diff --git a/docs/source/fileclasses.rst b/docs/source/fileclasses.rst deleted file mode 100644 index ddc2c9d..0000000 --- a/docs/source/fileclasses.rst +++ /dev/null @@ -1,15 +0,0 @@ -ogs5py.fileclasses -================== - -.. automodule:: ogs5py.fileclasses - -.. raw:: latex - - \clearpage - -.. toctree:: - :hidden: - - fileclasses.base.rst - fileclasses.gli.rst - fileclasses.msh.rst diff --git a/docs/source/reader.rst b/docs/source/reader.rst deleted file mode 100644 index 3df45c5..0000000 --- a/docs/source/reader.rst +++ /dev/null @@ -1,8 +0,0 @@ -ogs5py.reader -============= - -.. automodule:: ogs5py.reader - -.. raw:: latex - - \clearpage \ No newline at end of file diff --git a/docs/source/tools.download.rst b/docs/source/tools.download.rst deleted file mode 100755 index 1147c3a..0000000 --- a/docs/source/tools.download.rst +++ /dev/null @@ -1,8 +0,0 @@ -ogs5py.tools.download -===================== - -.. automodule:: ogs5py.tools.download - -.. raw:: latex - - \clearpage \ No newline at end of file diff --git a/docs/source/tools.output.rst b/docs/source/tools.output.rst deleted file mode 100755 index 3336ad0..0000000 --- a/docs/source/tools.output.rst +++ /dev/null @@ -1,12 +0,0 @@ -ogs5py.tools.output -=================== - -.. automodule:: ogs5py.tools.output - :members: - :undoc-members: - :inherited-members: - :show-inheritance: - -.. raw:: latex - - \clearpage \ No newline at end of file diff --git a/docs/source/tools.rst b/docs/source/tools.rst deleted file mode 100644 index d270225..0000000 --- a/docs/source/tools.rst +++ /dev/null @@ -1,18 +0,0 @@ -ogs5py.tools -============ - -.. automodule:: ogs5py.tools - -.. raw:: latex - - \clearpage - -.. toctree:: - :hidden: - - tools.tools.rst - tools.script.rst - tools.types.rst - tools.download.rst - tools.output.rst - tools.vtk_viewer.rst \ No newline at end of file diff --git a/docs/source/tools.script.rst b/docs/source/tools.script.rst deleted file mode 100644 index e040f02..0000000 --- a/docs/source/tools.script.rst +++ /dev/null @@ -1,8 +0,0 @@ -ogs5py.tools.script -=================== - -.. automodule:: ogs5py.tools.script - -.. raw:: latex - - \clearpage \ No newline at end of file diff --git a/docs/source/tools.tools.rst b/docs/source/tools.tools.rst deleted file mode 100644 index 777a3f3..0000000 --- a/docs/source/tools.tools.rst +++ /dev/null @@ -1,8 +0,0 @@ -ogs5py.tools.tools -================== - -.. automodule:: ogs5py.tools.tools - -.. raw:: latex - - \clearpage \ No newline at end of file diff --git a/docs/source/tools.types.rst b/docs/source/tools.types.rst deleted file mode 100644 index 75fb8af..0000000 --- a/docs/source/tools.types.rst +++ /dev/null @@ -1,10 +0,0 @@ -ogs5py.tools.types -================== - -.. automodule:: ogs5py.tools.types - :members: - :undoc-members: - -.. raw:: latex - - \clearpage \ No newline at end of file diff --git a/docs/source/tools.vtk_viewer.rst b/docs/source/tools.vtk_viewer.rst deleted file mode 100755 index e0a2620..0000000 --- a/docs/source/tools.vtk_viewer.rst +++ /dev/null @@ -1,12 +0,0 @@ -ogs5py.tools.vtk_viewer -======================= - -.. automodule:: ogs5py.tools.vtk_viewer - :members: - :undoc-members: - :inherited-members: - :show-inheritance: - -.. raw:: latex - - \clearpage \ No newline at end of file diff --git a/src/ogs5py/__init__.py b/src/ogs5py/__init__.py index 4c88fbd..da2a586 100644 --- a/src/ogs5py/__init__.py +++ b/src/ogs5py/__init__.py @@ -11,9 +11,11 @@ =========== .. autosummary:: - fileclasses - reader - tools + :toctree: api + + fileclasses + reader + tools Classes ======= @@ -23,7 +25,7 @@ Class to setup an ogs model .. autosummary:: - :toctree: generated + :toctree: api OGS diff --git a/src/ogs5py/fileclasses/__init__.py b/src/ogs5py/fileclasses/__init__.py index a78502f..7489289 100644 --- a/src/ogs5py/fileclasses/__init__.py +++ b/src/ogs5py/fileclasses/__init__.py @@ -8,6 +8,8 @@ ^^^^^^^^^^^ .. autosummary:: + :toctree: + base gli msh @@ -17,7 +19,7 @@ Classes for all OGS5 Files .. autosummary:: - :toctree: generated + :toctree: ASC BC diff --git a/src/ogs5py/fileclasses/base.py b/src/ogs5py/fileclasses/base.py index 7182d43..aad4802 100644 --- a/src/ogs5py/fileclasses/base.py +++ b/src/ogs5py/fileclasses/base.py @@ -8,7 +8,7 @@ ^^^^^^^^^^^^ .. autosummary:: - :toctree: generated + :toctree: File LineFile @@ -500,7 +500,7 @@ def get_block(self, index=None, as_dict=True): return main_key, sub_key, cont def update_block(self, index=None, main_key=None, **block): - """ + r""" Update a Block from the actual file. Parameters @@ -536,7 +536,7 @@ def update_block(self, index=None, main_key=None, **block): self.add_block(index=index, **upd_block) def add_block(self, index=None, main_key=None, **block): - """ + r""" Add a new Block to the actual file. Keywords are the sub keywords of the actual file type: @@ -617,7 +617,7 @@ def add_block(self, index=None, main_key=None, **block): self.add_multi_content(block[skey], main_index=index) def append_to_block(self, index=None, **block): - """ + r""" Append data to an existing Block in the actual file. Keywords are the sub keywords of the actual file type: @@ -1125,7 +1125,7 @@ def __repr__(self): class MultiFile: - """ + r""" Class holding mulitple files of the same type. Parameters @@ -1182,7 +1182,7 @@ def __getattr__(self, attr): return None def add(self, *args, **kwargs): - """Add a new instance of the base class with *args and **kwargs.""" + r"""Add a new instance of the base class with given args and kwargs.""" kw = copy.deepcopy(self.standard) kw.update(kwargs) self.append(self._base(*args, **kw)) diff --git a/src/ogs5py/fileclasses/gli/__init__.py b/src/ogs5py/fileclasses/gli/__init__.py index 2012dd9..0d5afd7 100644 --- a/src/ogs5py/fileclasses/gli/__init__.py +++ b/src/ogs5py/fileclasses/gli/__init__.py @@ -9,13 +9,16 @@ The generators can be called with :any:`GLI.generate` .. autosummary:: + :toctree: + generator File Classes ^^^^^^^^^^^^ +.. currentmodule:: ogs5py.fileclasses + .. autosummary:: - :toctree: generated GLI GLIext diff --git a/src/ogs5py/fileclasses/gli/core.py b/src/ogs5py/fileclasses/gli/core.py index 2b5f4ac..fede9ff 100644 --- a/src/ogs5py/fileclasses/gli/core.py +++ b/src/ogs5py/fileclasses/gli/core.py @@ -481,7 +481,7 @@ def generate(self, generator="rectangular", **kwargs): """ Use a gli-generator from the generator module. - See: :any:`ogs5py.fileclasses.gli.generator` + See: :py:mod:`ogs5py.fileclasses.gli.generator` Parameters ---------- diff --git a/src/ogs5py/fileclasses/gli/generator.py b/src/ogs5py/fileclasses/gli/generator.py index af5de8d..6bced53 100644 --- a/src/ogs5py/fileclasses/gli/generator.py +++ b/src/ogs5py/fileclasses/gli/generator.py @@ -9,7 +9,7 @@ These generators can be called with :any:`GLI.generate` .. autosummary:: - :toctree: generated + :toctree: rectangular radial diff --git a/src/ogs5py/fileclasses/msh/__init__.py b/src/ogs5py/fileclasses/msh/__init__.py index 2dd0baa..36b7dbb 100644 --- a/src/ogs5py/fileclasses/msh/__init__.py +++ b/src/ogs5py/fileclasses/msh/__init__.py @@ -6,16 +6,19 @@ Subpackages ^^^^^^^^^^^ -The generators can be called with :any:`MSH.generate` +The generators can be called with :py:meth:`~ogs5py.fileclasses.MSH.generate` .. autosummary:: + :toctree: + generator File Class ^^^^^^^^^^ +.. currentmodule:: ogs5py.fileclasses + .. autosummary:: - :toctree: generated MSH diff --git a/src/ogs5py/fileclasses/msh/core.py b/src/ogs5py/fileclasses/msh/core.py index 17ef394..cdb3e61 100644 --- a/src/ogs5py/fileclasses/msh/core.py +++ b/src/ogs5py/fileclasses/msh/core.py @@ -1000,7 +1000,7 @@ def generate(self, generator="rectangular", **kwargs): """ Use a mesh-generator from the generator module. - See: :any:`ogs5py.fileclasses.msh.generator` + See: :py:mod:`ogs5py.fileclasses.msh.generator` Parameters ---------- diff --git a/src/ogs5py/fileclasses/msh/generator.py b/src/ogs5py/fileclasses/msh/generator.py index db19e24..8f96825 100644 --- a/src/ogs5py/fileclasses/msh/generator.py +++ b/src/ogs5py/fileclasses/msh/generator.py @@ -9,7 +9,7 @@ These generators can be called with :any:`MSH.generate` .. autosummary:: - :toctree: generated + :toctree: rectangular radial diff --git a/src/ogs5py/ogs.py b/src/ogs5py/ogs.py index cc27212..e7efe34 100644 --- a/src/ogs5py/ogs.py +++ b/src/ogs5py/ogs.py @@ -1,18 +1,5 @@ # -*- coding: utf-8 -*- -""" -Base Class for an OGS5 run. - -.. currentmodule:: ogs5py.ogs - -OGS Class -^^^^^^^^^ - -.. autosummary:: - - OGS - ----- -""" +"""Base Class for an OGS5 run.""" import glob import os import shutil @@ -1022,7 +1009,7 @@ def output_files(self, pcs=None, typ="VTK", element=None, output_dir=None): specify the PCS type that should be collected Possible values are: - - None/"" (no PCS_TYPE specified in *.out) + - None/"" (no PCS_TYPE specified in \*.out) - "NO_PCS" - "GROUNDWATER_FLOW" - "LIQUID_FLOW" diff --git a/src/ogs5py/reader/__init__.py b/src/ogs5py/reader/__init__.py index 038009d..c2fac3d 100644 --- a/src/ogs5py/reader/__init__.py +++ b/src/ogs5py/reader/__init__.py @@ -8,7 +8,7 @@ ^^^^^^ .. autosummary:: - :toctree: generated + :toctree: readvtk readpvd diff --git a/src/ogs5py/tools/__init__.py b/src/ogs5py/tools/__init__.py index 6204d43..332e633 100644 --- a/src/ogs5py/tools/__init__.py +++ b/src/ogs5py/tools/__init__.py @@ -8,10 +8,12 @@ ^^^^^^^^^^^ .. autosummary:: - tools - script - download - output - vtk_viewer - types + :toctree: + + tools + script + download + output + vtk_viewer + types """ diff --git a/src/ogs5py/tools/download.py b/src/ogs5py/tools/download.py index ba212d0..d5e65f1 100755 --- a/src/ogs5py/tools/download.py +++ b/src/ogs5py/tools/download.py @@ -10,14 +10,12 @@ A downloading routine to get the OSG5 executable. .. autosummary:: - :toctree: generated + :toctree: download_ogs add_exe reset_download OGS5PY_CONFIG - ----- """ import os import platform diff --git a/src/ogs5py/tools/output.py b/src/ogs5py/tools/output.py index 08d514c..073abaa 100755 --- a/src/ogs5py/tools/output.py +++ b/src/ogs5py/tools/output.py @@ -1,5 +1,20 @@ # -*- coding: utf-8 -*- -"""Tools for ogs5py output files (independent from VTK package).""" +""" +Tools for ogs5py output files (independent from VTK package). + +.. currentmodule:: ogs5py.tools.output + +Helpers +^^^^^^^ + +.. autosummary:: + :toctree: + + get_output_files + readpvd_single + split_ply_path + split_pnt_path +""" import glob import os import re @@ -288,7 +303,7 @@ def readpvd_single(infile): def get_output_files(task_root, task_id, pcs=None, typ="VTK", element=None): - """ + r""" Get a list of output file paths. Parameters @@ -301,7 +316,7 @@ def get_output_files(task_root, task_id, pcs=None, typ="VTK", element=None): specify the PCS type that should be collected Possible values are: - - None/"" (no PCS_TYPE specified in *.out) + - None/"" (no PCS_TYPE specified in \*.out) - "NO_PCS" - "GROUNDWATER_FLOW" - "LIQUID_FLOW" diff --git a/src/ogs5py/tools/script.py b/src/ogs5py/tools/script.py index 7946c42..587df1a 100644 --- a/src/ogs5py/tools/script.py +++ b/src/ogs5py/tools/script.py @@ -8,7 +8,7 @@ ^^^^^^^^^ .. autosummary:: - :toctree: generated + :toctree: gen_script @@ -16,7 +16,7 @@ ^^^^^^^ .. autosummary:: - :toctree: generated + :toctree: formater get_line @@ -24,8 +24,6 @@ add_block_file add_load_file add_list_file - ----- """ import os import shutil diff --git a/src/ogs5py/tools/tools.py b/src/ogs5py/tools/tools.py index 036f614..350b4c4 100644 --- a/src/ogs5py/tools/tools.py +++ b/src/ogs5py/tools/tools.py @@ -8,7 +8,7 @@ ^^^^^^^ .. autosummary:: - :toctree: generated + :toctree: Output @@ -16,7 +16,7 @@ ^^^^^^^^^^^^ .. autosummary:: - :toctree: generated + :toctree: search_mkey uncomment @@ -37,7 +37,7 @@ ^^^^^^^^^^^^^^^ .. autosummary:: - :toctree: generated + :toctree: rotate_points shift_points @@ -51,15 +51,13 @@ ^^^^^^^^^^^ .. autosummary:: - :toctree: generated + :toctree: unique_rows replace by_id specialrange generate_time - ----- """ import ast import collections diff --git a/src/ogs5py/tools/types.py b/src/ogs5py/tools/types.py index 263c4d2..07baa72 100644 --- a/src/ogs5py/tools/types.py +++ b/src/ogs5py/tools/types.py @@ -54,6 +54,81 @@ OGS_EXT MULTI_FILES +---- + +.. autodata:: EMPTY_GLI + +.. autodata:: GLI_KEYS + +.. autodata:: GLI_KEY_LIST + +.. autodata:: EMPTY_PLY + +.. autodata:: PLY_KEYS + +.. autodata:: PLY_KEY_LIST + +.. autodata:: PLY_TYPES + +.. autodata:: EMPTY_SRF + +.. autodata:: SRF_KEYS + +.. autodata:: SRF_KEY_LIST + +.. autodata:: SRF_TYPES + +.. autodata:: EMPTY_VOL + +.. autodata:: VOL_KEYS + +.. autodata:: VOL_KEY_LIST + +.. autodata:: VOL_TYPES + +.. autodata:: EMPTY_MSH + +.. autodata:: MESH_KEYS + +.. autodata:: MESH_DATA_KEYS + +.. autodata:: ELEM_1D + +.. autodata:: ELEM_2D + +.. autodata:: ELEM_3D + +.. autodata:: ELEM_DIM + +.. autodata:: ELEM_NAMES + +.. autodata:: ELEM_TYP + +.. autodata:: ELEM_TYP1D + +.. autodata:: ELEM_TYP2D + +.. autodata:: ELEM_TYP3D + +.. autodata:: VTK_TYP + +.. autodata:: MESHIO_NAMES + +.. autodata:: NODE_NO + +.. autodata:: STRTYPE + +.. autodata:: PCS_TYP + +.. autodata:: PCS_EXT + +.. autodata:: PRIM_VAR + +.. autodata:: PRIM_VAR_BY_PCS + +.. autodata:: OGS_EXT + +.. autodata:: MULTI_FILES """ import numpy as np diff --git a/src/ogs5py/tools/vtk_viewer.py b/src/ogs5py/tools/vtk_viewer.py index 64937ac..6183442 100755 --- a/src/ogs5py/tools/vtk_viewer.py +++ b/src/ogs5py/tools/vtk_viewer.py @@ -1,5 +1,17 @@ # -*- coding: utf-8 -*- -"""Viewer for a vtk file.""" +""" +Viewer for a vtk file. + +.. currentmodule:: ogs5py.tools.vtk_viewer + +Viewer +^^^^^^ + +.. autosummary:: + :toctree: + + show_vtk +""" # import os # os.environ["QT_API"] = "pyqt" # os.environ["ETS_TOOLKIT"] = "qt4"