simplify docs

GeoStat-Framework · Apr 15, 2023 · 68aa24d · 68aa24d
1 parent 53c8b49
commit 68aa24d
Show file tree

Hide file tree

Showing 41 changed files with 183 additions and 228 deletions.
diff --git 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
@@ -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
@@ -178,7 +178,7 @@ You can contact us via <[email protected]>.
 
 ## 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
@@ -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
@@ -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
@@ -21,7 +21,7 @@
     <br />
     <br />
     <ul>
-      <Li><a href="genindex.html">Index</a></Li>
-      <Li><a href="contents.html">Sitemap</a></Li>
+      <Li><a href="{{ pathto('genindex') }}">Index</a></Li>
+      <Li><a href="{{ pathto(master_doc) }}">Sitemap</a></Li>
     </ul>
   {% endblock %}
diff --git a/docs/source/package.rst → docs/source/api.rst b/docs/source/package.rst → 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
@@ -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
@@ -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
diff --git a/docs/source/fileclasses.gli.generator.rst b/docs/source/fileclasses.gli.generator.rst
diff --git a/docs/source/fileclasses.gli.rst b/docs/source/fileclasses.gli.rst
diff --git a/docs/source/fileclasses.msh.generator.rst b/docs/source/fileclasses.msh.generator.rst
diff --git a/docs/source/fileclasses.msh.rst b/docs/source/fileclasses.msh.rst
diff --git a/docs/source/fileclasses.rst b/docs/source/fileclasses.rst
diff --git a/docs/source/reader.rst b/docs/source/reader.rst
diff --git a/docs/source/tools.download.rst b/docs/source/tools.download.rst
diff --git a/docs/source/tools.output.rst b/docs/source/tools.output.rst
diff --git a/docs/source/tools.rst b/docs/source/tools.rst
diff --git a/docs/source/tools.script.rst b/docs/source/tools.script.rst
diff --git a/docs/source/tools.tools.rst b/docs/source/tools.tools.rst
diff --git a/docs/source/tools.types.rst b/docs/source/tools.types.rst
diff --git a/docs/source/tools.vtk_viewer.rst b/docs/source/tools.vtk_viewer.rst
diff --git 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
@@ -8,6 +8,8 @@
 ^^^^^^^^^^^
 
 .. autosummary::
+   :toctree:
+
    base
    gli
    msh
@@ -17,7 +19,7 @@
 Classes for all OGS5 Files
 
 .. autosummary::
-   :toctree: generated
+   :toctree:
 
    ASC
    BC