DOC: centralize and update autodoc settings

Explicitly use `sphinx-autodoc-typehints` rather than its extension, as the extension just installs it anyway. Also move autodoc options to default options in `conf.py` and adjust some settings that fix autodoc typehint resolution.
equinor · Nov 6, 2023 · 3be7189 · 3be7189
1 parent 6324af9
commit 3be7189
Show file tree

Hide file tree

Showing 3 changed files with 20 additions and 100 deletions.
diff --git a/docs/apireference.rst b/docs/apireference.rst
@@ -24,10 +24,6 @@ Classes
 """""""
 
 .. autoclass:: xtgeo.RegularSurface
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
@@ -38,10 +34,6 @@ Classes
 """""""
 
 .. autoclass:: xtgeo.Surfaces
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
@@ -69,10 +61,6 @@ Classes
 """""""
 
 .. autoclass:: xtgeo.Points
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
@@ -92,10 +80,6 @@ Classes
 """""""
 
 .. autoclass:: xtgeo.Polygons
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
@@ -117,10 +101,6 @@ Classes
 """""""
 
 .. autoclass:: xtgeo.Well
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
@@ -131,10 +111,6 @@ Classes
 """""""
 
 .. autoclass:: xtgeo.Wells
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
@@ -152,10 +128,6 @@ Classes
 """""""
 
 .. autoclass:: xtgeo.BlockedWell
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
@@ -171,10 +143,6 @@ Classes
 """""""
 
 .. autoclass:: xtgeo.BlockedWells
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
@@ -196,10 +164,6 @@ Classes
 """""""
 
 .. autoclass:: xtgeo.Cube
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
@@ -220,10 +184,6 @@ Classes
 """""""
 
 .. autoclass:: xtgeo.Grid
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
@@ -241,10 +201,6 @@ Classes
 """""""
 
 .. autoclass:: xtgeo.GridProperty
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
@@ -255,10 +211,6 @@ Classes
 """""""
 
 .. autoclass:: xtgeo.GridProperties
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
@@ -273,10 +225,6 @@ RoxUtils
 """"""""
 
 .. autoclass:: xtgeo.RoxUtils
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
@@ -287,54 +235,34 @@ MetadataRegularSurface
 """"""""""""""""""""""
 
 .. autoclass:: xtgeo.MetaDataRegularSurface
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
 MetaDataRegularCube
 """""""""""""""""""
 
 .. autoclass:: xtgeo.MetaDataRegularCube
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
 MetaDataCPGeometry
 """"""""""""""""""
 
 .. autoclass:: xtgeo.MetaDataCPGeometry
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
 MetaDataCPProperty
 """"""""""""""""""
 
 .. autoclass:: xtgeo.MetaDataCPProperty
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
 MetaDataWell
 """"""""""""
 
 .. autoclass:: xtgeo.MetaDataWell
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
@@ -345,31 +273,19 @@ XSection
 """"""""
 
 .. autoclass:: xtgeo.plot.XSection
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
 Map
 """
 
 .. autoclass:: xtgeo.plot.Map
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
 
 Grid3DSlice
 """""""""""
 
 .. autoclass:: xtgeo.plot.Grid3DSlice
-    :members:
-    :show-inheritance:
-    :inherited-members:
-    :special-members: __init__
 
     .. autoclasstoc::
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,45 +1,49 @@
 # noqa # pylint: skip-file
 from datetime import date
 
-import xtgeo
 from autoclasstoc import PublicMethods
 
+import xtgeo
+
 version = xtgeo.__version__
 release = xtgeo.__version__
 project = "xtgeo"
 current_year = date.today().year
 copyright = "Equinor 2019 - " + str(current_year) + f" (XTGeo release {release})"
 
 extensions = [
+    "autoclasstoc",
     "myst_parser",
-    "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
     "sphinx.ext.mathjax",
-    "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
-    "sphinx_toolbox.more_autodoc.typehints",
+    "sphinx.ext.autodoc",
     "sphinx_toolbox.more_autosummary",
-    "autoclasstoc",
+    "sphinx_autodoc_typehints",
 ]
 
-autosummary_generate = True
-
-autoclass_content = "both"
-
 
 class RemainingPublicMethods(PublicMethods):
     # skip dunder methods
     def predicate(self, name, attr, meta):
         return super().predicate(name, attr, meta) and not name.startswith("__")
 
 
+autoclass_content = "both"
 autoclasstoc_sections = [
     "public-attrs",
     "public-methods",
 ]
-
-autodoc_typehints = "description"
-
+autosummary_generate = True
+autodoc_default_options = {
+    "inherited-members": True,
+    "members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+    "special-members": "__init__",
+}
+autodoc_typehints = "none"
 napoleon_include_special_with_doc = False
 
 # The suffix of source filenames.
@@ -48,7 +52,6 @@ def predicate(self, name, attr, meta):
 # The master toctree document.
 master_doc = "index"
 
-
 templates_path = ["_templates"]
 exclude_patterns = ["_build"]
 pygments_style = "sphinx"

diff --git a/pyproject.toml b/pyproject.toml
@@ -85,12 +85,13 @@ dev = [
     "pytest-xdist",
 ]
 docs = [
+    "autoclasstoc",
+    "myst-parser",
     "pydocstyle",
-    "Sphinx",
+    "sphinx",
+    "sphinx-autodoc-typehints",
     "sphinx-rtd-theme",
     "sphinx-toolbox",
-    "autoclasstoc",
-    "myst-parser",
 ]
 
 [tool.black]