From bcbfdeb011d4473e2c1765d01ac0d47fbdb4bc08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dieter=20Werthm=C3=BCller?= Date: Wed, 21 Apr 2021 23:43:08 +0200 Subject: [PATCH] Change theme (#50) - (Re)-Write some of the "Manual" docs, mostly stub files - Change to RTD theme - Change to sphinx_automod - Combine the three galleries into one - Create stub for external gallery - Re-worked README; added logo and badges; added readme to docs - Added CHANGELOG-file - Moved contributing and developer instructions to docs - Rework a bit the .gitignore --- .gitignore | 72 ++---------- docs/source/_static/style.css | 25 +++++ docs/source/_templates/base.rst | 10 -- docs/source/_templates/class.rst | 38 ------- docs/source/_templates/layout.html | 16 +++ docs/source/_templates/module.rst | 36 ------ docs/source/changelog.rst | 1 + docs/source/code-geological-formats.rst | 16 +++ docs/source/code-interfaces.rst | 4 + docs/source/code-reader.rst | 70 ++++++++++++ docs/source/code-structs.rst | 25 +++++ docs/source/code-utils.rst | 7 ++ docs/source/code-viz.rst | 7 ++ docs/source/code-writer.rst | 34 ++++++ docs/source/code.rst | 106 ------------------ docs/source/conf.py | 70 +++++------- docs/source/contributing.rst | 10 +- docs/source/external/index.rst | 6 + docs/source/index.rst | 51 +++++---- docs/source/installation.rst | 36 ------ docs/source/maintenance.rst | 24 ++-- docs/source/manual.rst | 6 + examples/README.rst | 2 + examples/examples/gempy_model.py | 2 +- requirements_dev.txt | 2 + subsurface/geological_formats/boreholes.py | 5 +- subsurface/reader/faults/faults.py | 5 +- subsurface/reader/mesh/surface_reader.py | 8 ++ subsurface/reader/mesh/surfaces_api.py | 4 +- subsurface/reader/profiles/profiles_core.py | 5 + subsurface/reader/read_netcdf.py | 3 + subsurface/reader/readers_data.py | 4 + subsurface/reader/topography/topo_core.py | 4 + subsurface/reader/volume/read_volume.py | 5 + subsurface/reader/volume/volume_utils.py | 3 + subsurface/reader/wells/pandas_to_welly.py | 3 + subsurface/reader/wells/well_files_reader.py | 5 + subsurface/reader/wells/wells_api.py | 5 +- subsurface/reader/wells/wells_utils.py | 7 +- subsurface/reader/wells/welly_reader.py | 6 + .../base_structures/common_data_utils.py | 5 +- .../base_structures/structured_data.py | 3 + .../base_structures/unstructured_data.py | 3 + subsurface/structs/structured_elements.py | 3 + subsurface/structs/unstructured_elements.py | 3 + subsurface/visualization/to_pyvista.py | 5 + subsurface/writer/to_rex/common.py | 2 + subsurface/writer/to_rex/data_struct.py | 3 + subsurface/writer/to_rex/gempy_to_rexfile.py | 7 ++ subsurface/writer/to_rex/material_encoder.py | 3 + subsurface/writer/to_rex/mesh_encoder.py | 3 + subsurface/writer/to_rex/rex_api.py | 5 +- subsurface/writer/to_rex/to_rex.py | 6 + subsurface/writer/to_rex/utils.py | 3 + 54 files changed, 426 insertions(+), 376 deletions(-) create mode 100644 docs/source/_static/style.css delete mode 100644 docs/source/_templates/base.rst delete mode 100644 docs/source/_templates/class.rst create mode 100644 docs/source/_templates/layout.html delete mode 100644 docs/source/_templates/module.rst create mode 100644 docs/source/changelog.rst create mode 100644 docs/source/code-geological-formats.rst create mode 100644 docs/source/code-interfaces.rst create mode 100644 docs/source/code-reader.rst create mode 100644 docs/source/code-structs.rst create mode 100644 docs/source/code-utils.rst create mode 100644 docs/source/code-viz.rst create mode 100644 docs/source/code-writer.rst delete mode 100644 docs/source/code.rst create mode 100644 docs/source/external/index.rst delete mode 100644 docs/source/installation.rst create mode 100644 docs/source/manual.rst create mode 100644 examples/README.rst diff --git a/.gitignore b/.gitignore index 478f5bd3..4f1e20fb 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,17 @@ +# Documentation +docs/build/ +docs/source/api/ +docs/source/gen_modules/ +docs/source/examples/ + +# Versioning subsurface/_version.py -# Example data files - we need to handle this better +# Example data files *.nc +*.json +*.le + # vscode .vscode/* @@ -31,17 +41,6 @@ wheels/ *.egg-info/ .installed.cfg *.egg -MANIFEST - -# PyInstaller -# Usually these files are written by a python script from a template -# before PyInstaller builds the exe, so as to inject date/other infos into it. -*.manifest -*.spec - -# Installer logs -pip-log.txt -pip-delete-this-directory.txt # Unit test / coverage reports htmlcov/ @@ -55,40 +54,12 @@ coverage.xml .hypothesis/ .pytest_cache/ -# Translations -*.mo -*.pot - -# Django stuff: -*.log -local_settings.py -db.sqlite3 - -# Flask stuff: -instance/ -.webassets-cache - -# Scrapy stuff: -.scrapy - -# Sphinx documentation -docs/_build/ - -# PyBuilder -target/ - # Jupyter Notebook .ipynb_checkpoints # pyenv .python-version -# celery beat schedule file -celerybeat-schedule - -# SageMath parsed files -*.sage.py - # Environments .env .venv @@ -101,24 +72,3 @@ venv.bak/ # Spyder project settings .spyderproject .spyproject - -# Rope project settings -.ropeproject - -# mkdocs documentation -/site - -# mypy -.mypy_cache/ -/tests/data/.~lock.well_based_temperature.csv# -/docs/build/ -/docs/source/ -!/docs/source/code.rst -!/docs/source/conf.py -!/docs/source/index.rst -!/docs/source/installation.rst -!/docs/source/_static/ -!/docs/source/_templates/ -/data/ - -.idea diff --git a/docs/source/_static/style.css b/docs/source/_static/style.css new file mode 100644 index 00000000..cb2a0c75 --- /dev/null +++ b/docs/source/_static/style.css @@ -0,0 +1,25 @@ +/* Customized styles */ + +/* Sidebar header background */ +.wy-side-nav-search, .wy-nav-top { + background: #1DB6ED; +} + +/* Sidebar header text */ +.wy-side-nav-search > div.version { + color: #ffffff; +} + +/* Navigation headings */ +.wy-menu .caption-text { + color: #de4c13; + font-weight: bold; +} + +/* + +- red of pyramid: #de4c13; +- yellow of pyramid: #debc13; +- "SWUNG" blue: #1DB6ED; + +*/ diff --git a/docs/source/_templates/base.rst b/docs/source/_templates/base.rst deleted file mode 100644 index f5185603..00000000 --- a/docs/source/_templates/base.rst +++ /dev/null @@ -1,10 +0,0 @@ -{{ fullname | escape | underline}} - -.. currentmodule:: {{ module }} - -.. auto{{ objtype }}:: {{ objname }} - -.. include:: ../gen_modules/backreferences/{{fullname}}.{{item}}examples -.. raw:: html - -
\ No newline at end of file diff --git a/docs/source/_templates/class.rst b/docs/source/_templates/class.rst deleted file mode 100644 index 3e9e6f2d..00000000 --- a/docs/source/_templates/class.rst +++ /dev/null @@ -1,38 +0,0 @@ -{{ fullname | escape | underline}} - -.. currentmodule:: {{ module }} - - -.. autoclass:: {{ objname }} - :no-undoc-members: - - {% block examples%} - .. rubric:: Examples using {{name}} - .. include:: ../gen_modules/backreferences/{{fullname}}.examples - .. raw:: html - -
- {% endblock %} - {% block methods %} - {% if methods %} - .. rubric:: Methods - .. autosummary:: - {% for item in methods %} - ~{{ name }}.{{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - - {% block attributes %} - {% if attributes %} - .. rubric:: Attributes - - .. autosummary:: - {% for item in attributes %} - ~{{ name }}.{{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - - - diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html new file mode 100644 index 00000000..3fcd78b3 --- /dev/null +++ b/docs/source/_templates/layout.html @@ -0,0 +1,16 @@ +{% extends "!layout.html" %} + +{% block menu %} + {{ super() }} + + {% if menu_links %} +

+ {{ menu_links_name }} +

+ + {% endif %} +{% endblock %} diff --git a/docs/source/_templates/module.rst b/docs/source/_templates/module.rst deleted file mode 100644 index 6ec89e05..00000000 --- a/docs/source/_templates/module.rst +++ /dev/null @@ -1,36 +0,0 @@ -{{ fullname | escape | underline}} - -.. automodule:: {{ fullname }} - - {% block functions %} - {% if functions %} - .. rubric:: Functions - - .. autosummary:: - {% for item in functions %} - {{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - - {% block classes %} - {% if classes %} - .. rubric:: Classes - - .. autosummary:: - {% for item in classes %} - {{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - - {% block exceptions %} - {% if exceptions %} - .. rubric:: Exceptions - - .. autosummary:: - {% for item in exceptions %} - {{ item }} - {%- endfor %} - {% endif %} - {% endblock %} diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst new file mode 100644 index 00000000..09929fe4 --- /dev/null +++ b/docs/source/changelog.rst @@ -0,0 +1 @@ +.. include:: ../../CHANGELOG.rst diff --git a/docs/source/code-geological-formats.rst b/docs/source/code-geological-formats.rst new file mode 100644 index 00000000..ab9d4b75 --- /dev/null +++ b/docs/source/code-geological-formats.rst @@ -0,0 +1,16 @@ +Geological Formats +================== + +.. automodule:: subsurface.geological_formats + +.. automodapi:: subsurface.geological_formats.boreholes + :no-inheritance-diagram: + +.. automodapi:: subsurface.geological_formats.fault + :no-inheritance-diagram: + +.. automodapi:: subsurface.geological_formats.segy_reader + :no-inheritance-diagram: + +.. automodapi:: subsurface.geological_formats.seismic + :no-inheritance-diagram: diff --git a/docs/source/code-interfaces.rst b/docs/source/code-interfaces.rst new file mode 100644 index 00000000..fa3485e2 --- /dev/null +++ b/docs/source/code-interfaces.rst @@ -0,0 +1,4 @@ +Interfaces +========== + +.. automodule:: subsurface.interfaces diff --git a/docs/source/code-reader.rst b/docs/source/code-reader.rst new file mode 100644 index 00000000..243a68bf --- /dev/null +++ b/docs/source/code-reader.rst @@ -0,0 +1,70 @@ +Reader +====== + +.. automodule:: subsurface.reader + +.. automodapi:: subsurface.reader.readers_data + :no-inheritance-diagram:reader + +.. automodapi:: subsurface.reader.read_netcdf + :no-inheritance-diagram:reader + + +.. automodule:: subsurface.reader.faults + +.. automodapi:: subsurface.reader.faults.faults + :no-inheritance-diagram:reader + + +.. automodule:: subsurface.reader.geo_object + + +.. automodule:: subsurface.reader.mesh + +.. automodapi:: subsurface.reader.mesh.surface_reader + :no-inheritance-diagram:reader + +.. automodapi:: subsurface.reader.mesh.surfaces_api + :no-inheritance-diagram:reader + + +.. automodule:: subsurface.reader.petrel + + +.. automodule:: subsurface.reader.profiles + +.. automodapi:: subsurface.reader.profiles.profiles_core + :no-inheritance-diagram:reader + + +.. automodule:: subsurface.reader.topography + +.. automodapi:: subsurface.reader.topography.topo_core + :no-inheritance-diagram:reader + + +.. automodule:: subsurface.reader.volume + +.. automodapi:: subsurface.reader.volume.read_volume + :no-inheritance-diagram:reader + +.. automodapi:: subsurface.reader.volume.volume_utils + :no-inheritance-diagram:reader + + +.. automodule:: subsurface.reader.wells + +.. automodapi:: subsurface.reader.wells.pandas_to_welly + :no-inheritance-diagram:reader + +.. automodapi:: subsurface.reader.wells.well_files_reader + :no-inheritance-diagram:reader + +.. automodapi:: subsurface.reader.wells.wells_api + :no-inheritance-diagram:reader + +.. automodapi:: subsurface.reader.wells.wells_utils + :no-inheritance-diagram:reader + +.. automodapi:: subsurface.reader.wells.welly_reader + :no-inheritance-diagram:reader diff --git a/docs/source/code-structs.rst b/docs/source/code-structs.rst new file mode 100644 index 00000000..4766a8dd --- /dev/null +++ b/docs/source/code-structs.rst @@ -0,0 +1,25 @@ +Structures +========== + +.. automodule:: subsurface.structs + +.. automodapi:: subsurface.structs.errors + :no-inheritance-diagram: + +.. automodapi:: subsurface.structs.structured_elements + :no-inheritance-diagram: + +.. automodapi:: subsurface.structs.unstructured_elements + :no-inheritance-diagram: + + +.. automodule:: subsurface.structs.base_structures + +.. automodapi:: subsurface.structs.base_structures.common_data_utils + :no-inheritance-diagram: + +.. automodapi:: subsurface.structs.base_structures.structured_data + :no-inheritance-diagram: + +.. automodapi:: subsurface.structs.base_structures.unstructured_data + :no-inheritance-diagram: diff --git a/docs/source/code-utils.rst b/docs/source/code-utils.rst new file mode 100644 index 00000000..749a8f28 --- /dev/null +++ b/docs/source/code-utils.rst @@ -0,0 +1,7 @@ +Utilities +========= + +.. automodule:: subsurface.utils + +.. automodapi:: subsurface.utils.utils_core + :no-inheritance-diagram: diff --git a/docs/source/code-viz.rst b/docs/source/code-viz.rst new file mode 100644 index 00000000..a3f7294e --- /dev/null +++ b/docs/source/code-viz.rst @@ -0,0 +1,7 @@ +Visualization +============= + +.. automodule:: subsurface.visualization + +.. automodapi:: subsurface.visualization.to_pyvista + :no-inheritance-diagram: diff --git a/docs/source/code-writer.rst b/docs/source/code-writer.rst new file mode 100644 index 00000000..6771a188 --- /dev/null +++ b/docs/source/code-writer.rst @@ -0,0 +1,34 @@ +Writer +====== + +.. automodule:: subsurface.writer + +.. automodapi:: subsurface.writer.to_binary + :no-inheritance-diagram:writer + + +.. automodule:: subsurface.writer.to_rex + +.. automodapi:: subsurface.writer.to_rex.common + :no-inheritance-diagram:writer + +.. automodapi:: subsurface.writer.to_rex.data_struct + :no-inheritance-diagram: + +.. automodapi:: subsurface.writer.to_rex.gempy_to_rexfile + :no-inheritance-diagram:writer + +.. automodapi:: subsurface.writer.to_rex.material_encoder + :no-inheritance-diagram:writer + +.. automodapi:: subsurface.writer.to_rex.mesh_encoder + :no-inheritance-diagram: + +.. automodapi:: subsurface.writer.to_rex.rex_api + :no-inheritance-diagram:writer + +.. automodapi:: subsurface.writer.to_rex.to_rex + :no-inheritance-diagram:writer + +.. automodapi:: subsurface.writer.to_rex.utils + :no-inheritance-diagram: diff --git a/docs/source/code.rst b/docs/source/code.rst deleted file mode 100644 index 8a46c635..00000000 --- a/docs/source/code.rst +++ /dev/null @@ -1,106 +0,0 @@ -Code -==== - -.. toctree:: - :maxdepth: 3 - - -Subsurface Base Structures --------------------------- -.. currentmodule:: subsurface -.. autosummary:: - :toctree: Base Structures - :template: class.rst - - UnstructuredData - StructuredData - - -.. currentmodule:: subsurface.structs.base_structures -.. autosummary:: - :toctree: Base Structures - :template: class.rst - - CommonDataMethods - -Unstructured Elements ---------------------- -.. currentmodule:: subsurface -.. autosummary:: - :toctree: Unstructured Elements - :template: class.rst - - PointSet - LineSet - TriSurf - TetraMesh - - -Structured Elements -------------------- -.. currentmodule:: subsurface -.. autosummary:: - :toctree: Structured Elements - :template: class.rst - - StructuredGrid - StructuredSurface - -Read Well Data --------------- -.. currentmodule:: subsurface.io -.. autosummary:: - :toctree: Read well data - :template: base.rst - - read_wells_to_unstruct - borehole_location_to_unstruct - -Read Topographic Data ---------------------- -.. currentmodule:: subsurface.io -.. autosummary:: - :toctree: Read topographic data - :template: base.rst - - read_unstructured_topography - read_structured_topography - -Read Profiles -------------- - -.. currentmodule:: subsurface.io -.. autosummary:: - :toctree: Read profiles - :template: base.rst - - lineset_from_trace - create_mesh_from_trace - create_tri_surf_from_traces_texture - -Read Surface ------------- -.. currentmodule:: subsurface.io.mesh.surface_reader -.. autosummary:: - :toctree: Surface reader - :template: base.rst - - csv_to_unstruct_args - dxf_to_vertex_edges - get_attributes_from_df - get_cells_from_df - -Plot ----- -.. currentmodule:: subsurface.visualization -.. autosummary:: - :toctree: Visualization - :template: base.rst - - pv_plot - to_pyvista_points - to_pyvista_line - to_pyvista_mesh - to_pyvista_mesh_and_texture - to_pyvista_tetra - update_grid_attribute \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 3a4d64f7..b56e8a7b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -29,9 +29,6 @@ # Load extensions extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', @@ -40,7 +37,12 @@ 'sphinx.ext.githubpages', 'sphinx.ext.napoleon', 'sphinx_gallery.gen_gallery', + 'sphinx_automodapi.automodapi', + 'sphinx_automodapi.smart_resolver', ] +autosummary_generate = True +add_module_names = True +numpydoc_show_class_members=False intersphinx_mapping = { 'numpy': ('https://numpy.org/doc/stable/', None), @@ -52,16 +54,7 @@ napoleon_google_docstring = True -autodoc_default_options = { - 'autodoc_default_flags': ['members'], - 'members': None, - 'member-order': 'bysource', - 'special-members': '__init__', - 'undoc-members': True, - 'exclude-members': '__weakref__' -} -autosummary_generate = True -autosummary_imported_members = False +description = 'DataHub for geoscientific data in Python.' # The templates path. templates_path = ['_templates'] @@ -95,14 +88,10 @@ sphinx_gallery_conf = { # path to your examples scripts "examples_dirs": [ - "../../examples/getting_started", - "../../examples/tutorials", - "../../examples/examples", + "../../examples/", ], # path where to save gallery generated examples "gallery_dirs": [ - 'getting_started', - 'tutorials', "examples", ], # Patter to search for example files @@ -129,37 +118,38 @@ } # -- Options for HTML output ---------------------------------------------- -html_theme = 'alabaster' - -# html theme options +html_theme = 'sphinx_rtd_theme' html_theme_options = { - 'github_user': 'softwareunderground', - 'github_repo': 'subsurface', - 'github_type': 'star', - 'logo': './logos/subsurface.png', - 'logo_name': True, - 'page_width': '1200px', - 'fixed_sidebar': False, - 'show_related': True, - 'sidebar_collapse': True, + 'logo_only': True, + 'display_version': True, + 'prev_next_buttons_location': 'both', } - -# Custom sidebar templates, maps document names to template names. -html_sidebars = {'**': ['about.html', 'navigation.html', - 'relations.html', - 'searchbox.html', - 'donate.html', ]} - -# Paths html_static_path = ['_static'] +html_logo = '_static/logos/subsurface.png' html_favicon = '_static/logos/favicon.ico' +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'searchbox.html', + ] +} +html_context = { + 'menu_links_name': 'Links', + 'menu_links': [ + (' Source Code', + 'https://github.com/softwareunderground/subsurface'), + ], +} -html_use_modindex = True -html_file_suffix = '.html' htmlhelp_basename = 'subsurface' # Remove matplotlib agg warnings from generated doc when using plt.show warnings.filterwarnings("ignore", category=UserWarning, message='Matplotlib is currently using agg, which is a' ' non-GUI backend, so cannot show the figure.') + +# -- CSS fixes -- +def setup(app): + app.add_css_file("style.css") diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index 8c652a18..8523392b 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -1,8 +1,10 @@ -Contributing to `subsurface` ----------------------------- +Contributing +------------ + +The package ``subsurface`` is a community effort, and contributions of any kind +(code, documentation, bug reports, examples) are very welcomed; please get in +touch! .. todo:: Write! - -Contributions are welcome. diff --git a/docs/source/external/index.rst b/docs/source/external/index.rst new file mode 100644 index 00000000..2cfed25f --- /dev/null +++ b/docs/source/external/index.rst @@ -0,0 +1,6 @@ +External Examples +================= + +.. todo:: + + Replace this directory by a gallery of linked, external examples. diff --git a/docs/source/index.rst b/docs/source/index.rst index e418e2a2..c4309746 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -11,43 +11,54 @@ subsurface Documentation ---- - .. include:: ../../README.rst :start-after: sphinx-inclusion-marker -Contents: + +Requirements +------------ + +The **only** requirement for ``subsurface`` is ``xarray`` (which, in turn, +requires ``pandas`` and ``numpy``). + + +Optional requirements +--------------------- + +There are many optional requirements, depending on the data format you want to +read/write. Currently, the ``requierements_opt.txt`` reads like: + +.. include:: ../../requirements_opt.txt + :literal: + .. toctree:: :maxdepth: 2 + :hidden: + :caption: User Guide - installation + manual changelog contributing maintenance .. toctree:: :maxdepth: 2 - :caption: Getting started + :hidden: + :caption: Galleries - getting_started/index - tutorials/index examples/index + external/index .. toctree:: :maxdepth: 2 + :hidden: :caption: API Reference - code - - -References ----------- - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`search` - - + code-geological-formats + code-interfaces + code-reader + code-structs + code-utils + code-viz + code-writer diff --git a/docs/source/installation.rst b/docs/source/installation.rst deleted file mode 100644 index d0534815..00000000 --- a/docs/source/installation.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. role:: raw-html-m2r(raw) - :format: html - - -Installation ------------- - -``$ pip install subsurface`` - - -Dependencies -^^^^^^^^^^^^ - -``GemPy`` requires Python 3.x and makes use of numerous open-source libraries: - -* pandas~=1.0.5 -* xarray~=0.16.1 -* numpy~=1.19.4 -* pytest~=6.1.2 -* setuptools~=50.3.1 -* typing~=3.7.4.3 - -Optional requirements: - -* segyio -* matplotlib~=3.3.3 -* pyvista~=0.27.2 -* xlrd # For reading xlsx -* geopandas~=0.8.1 -* rasterio~=1.1.8 -* imageio~=2.9.0 -* scipy~=1.5.4 -* shapely~=1.7.1 -* requests~=2.25.0 - - diff --git a/docs/source/maintenance.rst b/docs/source/maintenance.rst index fe090d39..e7952543 100644 --- a/docs/source/maintenance.rst +++ b/docs/source/maintenance.rst @@ -1,31 +1,23 @@ Maintenance =========== -.. todo:: - - TODO - - - Making a release ---------------- -- Adding release notes to CHANGELOG.rst. -- Create a release on GitHub (add the above release notes to it). This will run - the tests, and then automatically deploy it to PyPI, from where conda-forge - will pick it up as well. If everything works fine it should be available from - PyPI within minutes after the tests passed, and within an hour or two from - conda-forge. +1. Add release notes to ``CHANGELOG.rst``. +2. Create a release on GitHub, add the above release notes to it. +When you create a release on GitHub it will run the tests, and subsequently +deploy the version to PyPI, from where it will also be picked up to +conda-forge. If everything works fine it should be available from PyPI within +minutes after the tests passed, and within an hour or two from conda-forge. -Notes ------ .. note:: **Important.** Due to the use of ``setuptools_scm``, everything is by - default added to the wheel on PyPI. Documents that should not be in a - release have to be excluded by adding it to the ``MANIFEST.in``. + default added to the wheel on PyPI. Files and folders that should not be in + a release have to be excluded by adding it to the ``MANIFEST.in``. Type of commits diff --git a/docs/source/manual.rst b/docs/source/manual.rst new file mode 100644 index 00000000..2556805c --- /dev/null +++ b/docs/source/manual.rst @@ -0,0 +1,6 @@ +Manual +====== + +.. todo:: + + Add a basic user manual diff --git a/examples/README.rst b/examples/README.rst new file mode 100644 index 00000000..9f935a38 --- /dev/null +++ b/examples/README.rst @@ -0,0 +1,2 @@ +Examples +******** diff --git a/examples/examples/gempy_model.py b/examples/examples/gempy_model.py index d9e75d4e..ab109154 100644 --- a/examples/examples/gempy_model.py +++ b/examples/examples/gempy_model.py @@ -1,6 +1,6 @@ """ Reading Simple GemPy model in Subsurface -================================= +======================================== """ import sys diff --git a/requirements_dev.txt b/requirements_dev.txt index 6f1fa24f..a24ab6ce 100644 --- a/requirements_dev.txt +++ b/requirements_dev.txt @@ -5,6 +5,8 @@ # FOR DOCUMENTATION sphinx sphinx_gallery +sphinx_rtd_theme +sphinx_automodapi # FOR TESTING pytest diff --git a/subsurface/geological_formats/boreholes.py b/subsurface/geological_formats/boreholes.py index ad1d7098..81537d0a 100644 --- a/subsurface/geological_formats/boreholes.py +++ b/subsurface/geological_formats/boreholes.py @@ -1,6 +1,9 @@ from subsurface.structs import LineSet +__all__ = ['LineSet', ] + + class BoreholeSet(): def __init__(self, line_set: LineSet): - self.geometry = line_set \ No newline at end of file + self.geometry = line_set diff --git a/subsurface/reader/faults/faults.py b/subsurface/reader/faults/faults.py index a6cdc7e9..8ef2cbb5 100644 --- a/subsurface/reader/faults/faults.py +++ b/subsurface/reader/faults/faults.py @@ -7,6 +7,9 @@ import pandas as pd +__all__ = ['read_faultsticks_kingdom', 'read_faultsticks_charisma'] + + def read_faultsticks_kingdom(fp: str, name=None): """ Reads in Kingdom fault stick files (kingdom) exported from Petrel (tested @@ -74,4 +77,4 @@ def read_faultsticks_charisma(fp:str, name=None): df = pd.DataFrame(storage) df.columns = ["X", "Y", "Z", "name", "stick id"] - return df \ No newline at end of file + return df diff --git a/subsurface/reader/mesh/surface_reader.py b/subsurface/reader/mesh/surface_reader.py index a7834efa..e1b57b82 100644 --- a/subsurface/reader/mesh/surface_reader.py +++ b/subsurface/reader/mesh/surface_reader.py @@ -7,6 +7,13 @@ import numpy as np +__all__ = ['read_mesh_file_to_vertex', 'read_mesh_file_to_cells', + 'read_mesh_file_to_attr', 'mesh_csv_to_vertex', 'mesh_csv_to_cells', + 'mesh_csv_to_attributes', 'get_cells_from_df', + 'cells_from_delaunay', 'get_vertices_from_df', 'map_columns_names', + 'dxf_to_vertex_edges', 'dxf_to_vertex'] + + def read_mesh_file_to_vertex(reader_args: ReaderFilesHelper) -> np.ndarray: if reader_args.format == '.csv': vertex = mesh_csv_to_vertex(reader_args.file_or_buffer, reader_args.columns_map, @@ -63,6 +70,7 @@ def mesh_csv_to_attributes(path_to_file: str, map_columns_names(columns_map, data) return data + def get_cells_from_df(data): try: cells = data[['e1', 'e2', 'e3']].dropna().astype('int').values diff --git a/subsurface/reader/mesh/surfaces_api.py b/subsurface/reader/mesh/surfaces_api.py index 09bd8489..57e3b138 100644 --- a/subsurface/reader/mesh/surfaces_api.py +++ b/subsurface/reader/mesh/surfaces_api.py @@ -4,6 +4,8 @@ cells_from_delaunay, read_mesh_file_to_attr from subsurface.reader.readers_data import ReaderUnstructuredHelper, RawDataOptions, RawDataUnstructured +__all__ = ['read_2d_mesh_to_unstruct', ] + def read_2d_mesh_to_unstruct(reader_args: ReaderUnstructuredHelper, raw_data_options: RawDataOptions = None, @@ -45,4 +47,4 @@ def read_2d_mesh_to_unstruct(reader_args: ReaderUnstructuredHelper, if raw_data_options.swap_yz_cells: raw_data.swap_yz_col_cells() ud = UnstructuredData.from_raw_data(raw_data) - return ud \ No newline at end of file + return ud diff --git a/subsurface/reader/profiles/profiles_core.py b/subsurface/reader/profiles/profiles_core.py index 4c0683bd..8e55b4c8 100644 --- a/subsurface/reader/profiles/profiles_core.py +++ b/subsurface/reader/profiles/profiles_core.py @@ -7,6 +7,11 @@ from subsurface.visualization import to_pyvista_mesh_and_texture, to_pyvista_line +__all__ = ['create_mesh_from_trace', 'create_tri_surf_from_traces_texture', + 'base_structs_to_tri_surf', 'traces_texture_to_sub_structs', + 'lineset_from_trace'] + + def create_mesh_from_trace(linestring, zmax: Union[float, int], zmin: Union[float, int], diff --git a/subsurface/reader/read_netcdf.py b/subsurface/reader/read_netcdf.py index 18a8d68f..dd5042d0 100644 --- a/subsurface/reader/read_netcdf.py +++ b/subsurface/reader/read_netcdf.py @@ -5,6 +5,9 @@ from subsurface import UnstructuredData, StructuredData +__all__ = ['read_unstruct', 'read_struct'] + + def read_unstruct(path, legacy=False, **kwargs): ds = xr.open_dataset(path, **kwargs) diff --git a/subsurface/reader/readers_data.py b/subsurface/reader/readers_data.py index 08d1d5a4..e034ed43 100644 --- a/subsurface/reader/readers_data.py +++ b/subsurface/reader/readers_data.py @@ -11,6 +11,10 @@ from subsurface.utils.utils_core import get_extension +__all__ = ['ReaderFilesHelper', 'ReaderUnstructuredHelper', + 'ReaderWellsHelper', 'RawDataOptions', 'RawDataUnstructured'] + + @dataclass class ReaderFilesHelper: file_or_buffer: FilePathOrBuffer diff --git a/subsurface/reader/topography/topo_core.py b/subsurface/reader/topography/topo_core.py index 8c76af46..0eac83d4 100644 --- a/subsurface/reader/topography/topo_core.py +++ b/subsurface/reader/topography/topo_core.py @@ -6,6 +6,10 @@ from subsurface.utils.utils_core import get_extension +__all__ = ['read_structured_topography', 'rasterio_dataset_to_structured_data', + 'read_unstructured_topography'] + + def read_structured_topography(path) -> StructuredData: import rasterio diff --git a/subsurface/reader/volume/read_volume.py b/subsurface/reader/volume/read_volume.py index 69ffffcb..786ce537 100644 --- a/subsurface/reader/volume/read_volume.py +++ b/subsurface/reader/volume/read_volume.py @@ -4,6 +4,11 @@ import pandas as pd +__all__ = ['read_volumetric_mesh_to_subsurface', + 'read_volumetric_mesh_coord_file', + 'read_volumetric_mesh_attr_file'] + + def read_volumetric_mesh_to_subsurface(reader_helper_coord: ReaderFilesHelper, reader_helper_attr: ReaderFilesHelper) -> UnstructuredData: df_coord = read_volumetric_mesh_coord_file(reader_helper_coord) diff --git a/subsurface/reader/volume/volume_utils.py b/subsurface/reader/volume/volume_utils.py index 36235935..ef5ec414 100644 --- a/subsurface/reader/volume/volume_utils.py +++ b/subsurface/reader/volume/volume_utils.py @@ -6,6 +6,9 @@ from subsurface.structs import UnstructuredData, StructuredData +__all__ = ['interpolate_unstructured_data_to_structured_data', ] + + def interpolate_unstructured_data_to_structured_data(ud: UnstructuredData, attr_name: str, resolution: List[int] = None) -> StructuredData: if resolution is None: diff --git a/subsurface/reader/wells/pandas_to_welly.py b/subsurface/reader/wells/pandas_to_welly.py index b982d019..4bbcf5ec 100644 --- a/subsurface/reader/wells/pandas_to_welly.py +++ b/subsurface/reader/wells/pandas_to_welly.py @@ -12,6 +12,9 @@ welly_imported = False +__all__ = ['WellyToSubsurfaceHelper', ] + + class WellyToSubsurfaceHelper: def __init__(self, collar_df: pd.DataFrame = None, diff --git a/subsurface/reader/wells/well_files_reader.py b/subsurface/reader/wells/well_files_reader.py index d07d4e5f..9d250856 100644 --- a/subsurface/reader/wells/well_files_reader.py +++ b/subsurface/reader/wells/well_files_reader.py @@ -7,6 +7,11 @@ from subsurface.reader.wells.wells_utils import add_tops_from_base_and_altitude_in_place +__all__ = ['read_borehole_files', 'read_collar', 'read_survey', 'read_lith', + 'read_attributes', 'check_format_and_read_to_df', + 'map_rows_and_cols_inplace'] + + def read_borehole_files(reader_wells_helper: ReaderWellsHelper) -> Dict[str, pd.DataFrame]: data_frames = dict() diff --git a/subsurface/reader/wells/wells_api.py b/subsurface/reader/wells/wells_api.py index 86d56fd2..6e70ee4e 100644 --- a/subsurface/reader/wells/wells_api.py +++ b/subsurface/reader/wells/wells_api.py @@ -13,6 +13,9 @@ from subsurface.reader.wells import read_collar +__all__ = ['read_wells_to_unstruct', 'borehole_location_to_unstruct'] + + def read_wells_to_unstruct(reader_wells_helper: ReaderWellsHelper, backend='welly', n_vertex_per_well=80, table: List[Component] = None) -> UnstructuredData: @@ -62,4 +65,4 @@ def borehole_location_to_unstruct(reader_helper: ReaderFilesHelper, cells_attr=collars_attributes.astype('float32'), xarray_attributes={"wells_names": wells_names.values.tolist()}) # TODO: This should be int16! - return ud \ No newline at end of file + return ud diff --git a/subsurface/reader/wells/wells_utils.py b/subsurface/reader/wells/wells_utils.py index 8969c7c9..ab8bd3f7 100644 --- a/subsurface/reader/wells/wells_utils.py +++ b/subsurface/reader/wells/wells_utils.py @@ -3,6 +3,11 @@ import pandas as pd +__all__ = ['add_tops_from_base_and_altitude_in_place', + 'fix_wells_higher_base_than_top_inplace', 'map_attr_to_segments', + 'pivot_wells_df_into_segment_per_row'] + + def add_tops_from_base_and_altitude_in_place(data: pd.DataFrame, col_well_name: str, col_base: str, col_altitude: str) -> pd.DataFrame: d = data @@ -36,8 +41,6 @@ def pivot_wells_df_into_segment_per_row(df: pd.DataFrame, start_segment_cols: in return df_fixed - - def _add_md_col_if_missing(d): if "md" not in d.columns: d.loc[:, 'md'] = d['top'] diff --git a/subsurface/reader/wells/welly_reader.py b/subsurface/reader/wells/welly_reader.py index aab76707..524c72f1 100644 --- a/subsurface/reader/wells/welly_reader.py +++ b/subsurface/reader/wells/welly_reader.py @@ -11,6 +11,12 @@ from striplog import Striplog, Component +__all__ = ['welly_to_subsurface', 'striplog_to_curve_log', + 'change_curve_basis_to_n_vertex_per_well_inplace', + 'vertex_and_cells_from_welly_trajectory', + 'well_without_valid_survey'] + + def welly_to_subsurface(wts: WellyToSubsurfaceHelper, elev=True, n_vertex_per_well=50, diff --git a/subsurface/structs/base_structures/common_data_utils.py b/subsurface/structs/base_structures/common_data_utils.py index 8c86c64d..9da7e8ec 100644 --- a/subsurface/structs/base_structures/common_data_utils.py +++ b/subsurface/structs/base_structures/common_data_utils.py @@ -5,6 +5,9 @@ from subsurface.structs.base_structures.unstructured_data import UnstructuredData +__all__ = ['replace_outliers', 'to_netcdf', 'default_path_and_name'] + + def replace_outliers(base_data: Union[StructuredData, UnstructuredData], dim=0, perc=0.99, replace_for=None): """@Edoardo Guerreiro https://stackoverflow.com/questions/60816533/ is-there-a-built-in-function-in-xarray-to-remove-outliers-from-a-dataset""" @@ -45,4 +48,4 @@ def default_path_and_name(path, name='subsurface_data.nc', ): else: os.makedirs(f'{path}') path = f'{path}/{name}' - return name, path \ No newline at end of file + return name, path diff --git a/subsurface/structs/base_structures/structured_data.py b/subsurface/structs/base_structures/structured_data.py index 45f7b755..0eadbb30 100644 --- a/subsurface/structs/base_structures/structured_data.py +++ b/subsurface/structs/base_structures/structured_data.py @@ -5,6 +5,9 @@ import xarray as xr +__all__ = ['StructuredData', ] + + @dataclass(frozen=True) class StructuredData: data: xr.Dataset diff --git a/subsurface/structs/base_structures/unstructured_data.py b/subsurface/structs/base_structures/unstructured_data.py index b5f5f0fc..2f386390 100644 --- a/subsurface/structs/base_structures/unstructured_data.py +++ b/subsurface/structs/base_structures/unstructured_data.py @@ -8,6 +8,9 @@ from subsurface.reader.readers_data import RawDataUnstructured +__all__ = ['UnstructuredData', ] + + @dataclass(frozen=True) class UnstructuredData: data: xr.Dataset diff --git a/subsurface/structs/structured_elements.py b/subsurface/structs/structured_elements.py index b1f9d615..9134dcc9 100644 --- a/subsurface/structs/structured_elements.py +++ b/subsurface/structs/structured_elements.py @@ -6,6 +6,9 @@ from .base_structures import StructuredData +__all__ = ['OctreeMesh', 'StructuredSurface', 'StructuredGrid'] + + class OctreeMesh: """ TODO: implement as Dom discussed with data frames to track the levels. diff --git a/subsurface/structs/unstructured_elements.py b/subsurface/structs/unstructured_elements.py index 54f3dfc1..5a52a0fb 100644 --- a/subsurface/structs/unstructured_elements.py +++ b/subsurface/structs/unstructured_elements.py @@ -14,6 +14,9 @@ from .base_structures import UnstructuredData, StructuredData +__all__ = ['PointSet', 'TriSurf', 'LineSet', 'TetraMesh'] + + class PointSet: """Class for pointset based data structures. diff --git a/subsurface/visualization/to_pyvista.py b/subsurface/visualization/to_pyvista.py index aa8b8e05..2164381a 100644 --- a/subsurface/visualization/to_pyvista.py +++ b/subsurface/visualization/to_pyvista.py @@ -16,6 +16,11 @@ background_plotter_imported = False +__all__ = ['pv_plot', 'to_pyvista_points', 'to_pyvista_mesh', + 'to_pyvista_mesh_and_texture', 'to_pyvista_line', + 'to_pyvista_tetra', 'to_pyvista_grid', 'update_grid_attribute'] + + def pv_plot(meshes: list, image_2d=False, ve=None, diff --git a/subsurface/writer/to_rex/common.py b/subsurface/writer/to_rex/common.py index 98788e85..ae2ad357 100644 --- a/subsurface/writer/to_rex/common.py +++ b/subsurface/writer/to_rex/common.py @@ -1,5 +1,7 @@ import numpy as np +__all__ = ['write_data_block_header', 'encode'] + rexFileHeaderSize = 64 rexCoordSize = 22 diff --git a/subsurface/writer/to_rex/data_struct.py b/subsurface/writer/to_rex/data_struct.py index a1cc11e1..6173961a 100644 --- a/subsurface/writer/to_rex/data_struct.py +++ b/subsurface/writer/to_rex/data_struct.py @@ -3,6 +3,9 @@ import numpy as np +__all__ = ['RexMesh', 'RexMaterial', 'RexLineSet'] + + @dataclass class RexMesh: """Data structure that can be converted to rex binary. Represent diff --git a/subsurface/writer/to_rex/gempy_to_rexfile.py b/subsurface/writer/to_rex/gempy_to_rexfile.py index 12f72f08..87538178 100644 --- a/subsurface/writer/to_rex/gempy_to_rexfile.py +++ b/subsurface/writer/to_rex/gempy_to_rexfile.py @@ -10,6 +10,13 @@ import matplotlib.colors as mcolors import pandas as pd + +__all__ = ['GemPyToRex', 'encode', 'write_file_header_block', + 'write_data_block_header', 'write_mesh_header', + 'write_mesh_coordinates', 'write_material_data', 'hex_to_rgb', + 'geomodel_to_rex', 'mesh_preprocess', 'write_file', 'write_rex', ] + + rexFileHeaderSize = 64 rexCoordSize = 22 diff --git a/subsurface/writer/to_rex/material_encoder.py b/subsurface/writer/to_rex/material_encoder.py index 3d8510d6..95788762 100644 --- a/subsurface/writer/to_rex/material_encoder.py +++ b/subsurface/writer/to_rex/material_encoder.py @@ -2,6 +2,9 @@ from subsurface.writer.to_rex.data_struct import RexMaterial +__all__ = ['material_encode', 'write_material_data'] + + def material_encode(rex_material: RexMaterial, data_id: int): # Write data block header for Material data_header_bytes = write_data_block_header( diff --git a/subsurface/writer/to_rex/mesh_encoder.py b/subsurface/writer/to_rex/mesh_encoder.py index ec0ec70f..6371e524 100644 --- a/subsurface/writer/to_rex/mesh_encoder.py +++ b/subsurface/writer/to_rex/mesh_encoder.py @@ -3,6 +3,9 @@ from subsurface.writer.to_rex.data_struct import RexMesh +__all__ = ['mesh_encode', 'write_mesh_coordinates', 'write_mesh_header'] + + def mesh_encode(rex_mesh: RexMesh, data_id: int): material_id = rex_mesh.material_id n_vtx_coord = rex_mesh.n_vtx diff --git a/subsurface/writer/to_rex/rex_api.py b/subsurface/writer/to_rex/rex_api.py index f67843cd..d52f4981 100644 --- a/subsurface/writer/to_rex/rex_api.py +++ b/subsurface/writer/to_rex/rex_api.py @@ -11,6 +11,9 @@ package_directory = os.path.dirname(os.path.abspath(__file__)) +__all__ = ['RexAPI', 'Rextag', 'upload_to_rexcloud'] + + class RexAPI: def __init__(self, project_name, api_token=None, secret=None): @@ -266,7 +269,7 @@ def upload_to_rexcloud(infiles : list, project_name=None, **kwargs): an ar code is plotted that can be scanned with the rexview app to show the model in vr. the qr code is plotted in ascii to the standard output, if the qr code is not recognizable, - try to revert the colors o0f the terminal output by setting reverse=False in thew show_tag() Method. + try to revert the colors o0f the terminal output by setting reverse=False in thew show_tag() Method. all api calls are python implementation of the Rex os api: https://www.rexos.org/rex-api/#tutorial-rex-project-before-you-begin diff --git a/subsurface/writer/to_rex/to_rex.py b/subsurface/writer/to_rex/to_rex.py index 1a6840d5..3151a26d 100644 --- a/subsurface/writer/to_rex/to_rex.py +++ b/subsurface/writer/to_rex/to_rex.py @@ -6,6 +6,12 @@ from subsurface.writer.to_rex.mesh_encoder import mesh_encode +__all__ = ['numpy_to_rex', 'w_data_blocks', 'w_block_data_type', + 'w_file_header_and_coord_system_block', + 'w_file_header_and_coord_system_block', 'write_rex_file', + 'read_rex_file'] + + def numpy_to_rex( rex_line_set: List[RexLineSet] = None, rex_meshes: List[RexMesh] = None, diff --git a/subsurface/writer/to_rex/utils.py b/subsurface/writer/to_rex/utils.py index 1fa0dee1..1b1ad0b0 100644 --- a/subsurface/writer/to_rex/utils.py +++ b/subsurface/writer/to_rex/utils.py @@ -1,6 +1,9 @@ import numpy as np +__all__ = ['hex_to_rgb', ] + + def hex_to_rgb(hex: str, normalize: bool = True) -> np.ndarray: """Transform colors from hex to rgb""" hex = hex.lstrip('#')