do not run pyupgrade on dataclasses, remove sphinx-autosummary-accessors, use sphinx-autodoc, add module API to docs, remove numpydoc from sphinx extensions, docstring fixes

Author: Zeitsperre

.pre-commit-config.yaml

@@ -7,6 +7,7 @@ repos:
     hooks:
       - id: pyupgrade
         args: [ '--py39-plus' ]
+        exclude: 'src/xncml/generated/ncml_2_2.py'
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:

CI/environment-docs.yml

@@ -18,7 +18,6 @@ dependencies:
   - jupyter_client
   - nbsphinx >=0.9.5
   - sphinx >=7.0.0
-#  - sphinx-autosummary-accessors
   - sphinx-codeautolink >=0.16.2
   - sphinx-copybutton
   - sphinx-rtd-theme >=1.0

CONTRIBUTING.rst

@@ -122,6 +122,7 @@ Ready to contribute? Here's how to set up ``xncml`` for local development.
 #. When you're done making changes, we **strongly** suggest running the tests in your environment or with the help of ``tox``:
 
     .. code-block:: console
+
         make lint
         python -m pytest
         # Or, to run multiple build tests

docs/apidoc/xncml.generated.rst

@@ -3,9 +3,9 @@ xncml.generated package
 
 .. automodule:: xncml.generated
    :members:
-   :undoc-members:
-   :show-inheritance:
    :private-members:
+   :show-inheritance:
+   :undoc-members:
 
 Submodules
 ----------
@@ -15,6 +15,6 @@ xncml.generated.ncml\_2\_2 module
 
 .. automodule:: xncml.generated.ncml_2_2
    :members:
-   :undoc-members:
-   :show-inheritance:
    :private-members:
+   :show-inheritance:
+   :undoc-members:

docs/apidoc/xncml.rst

@@ -3,9 +3,9 @@ xncml package
 
 .. automodule:: xncml
    :members:
-   :undoc-members:
-   :show-inheritance:
    :private-members:
+   :show-inheritance:
+   :undoc-members:
 
 Subpackages
 -----------
@@ -23,15 +23,15 @@ xncml.core module
 
 .. automodule:: xncml.core
    :members:
-   :undoc-members:
-   :show-inheritance:
    :private-members:
+   :show-inheritance:
+   :undoc-members:
 
 xncml.parser module
 -------------------
 
 .. automodule:: xncml.parser
    :members:
-   :undoc-members:
-   :show-inheritance:
    :private-members:
+   :show-inheritance:
+   :undoc-members:

docs/conf.py

@@ -35,17 +35,16 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.autosummary',
+    'sphinx.ext.autosectionlabel',
     'sphinx.ext.doctest',
-    'sphinx.ext.intersphinx',
     'sphinx.ext.extlinks',
-    'numpydoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
     'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive',
     'nbsphinx',
-    'sphinx.ext.autosectionlabel',
-    'sphinx.ext.todo',
     'sphinx_codeautolink',
     'sphinx_copybutton',
 ]

docs/index.rst

@@ -1,5 +1,3 @@
-.. module:: xncml
-
 Xncml Documentation
 ===================
 
@@ -14,6 +12,12 @@ Xncml Documentation
    authors
    changelog
 
+.. toctree::
+   :maxdepth: 1
+   :caption: API Reference:
+
+   apidoc/modules
+
 `xncml` adds NcML support to xarray. It includes utilities to modify NcML documents, and open NcML files as `xarray.Dataset`.
 For more information on NcML, take a look at `tutorials and examples <https://docs.unidata.ucar.edu/netcdf-java/current/userguide/basic_ncml_tutorial.html>`_
 and the `annotated schema <https://docs.unidata.ucar.edu/netcdf-java/current/userguide/annotated_ncml_schema.html>`_.

pyproject.toml

@@ -307,7 +307,7 @@ max-complexity = 15
 [tool.ruff.lint.per-file-ignores]
 "docs/**" = ["E402"]
 "src/xncml/**/__init__.py" = ["F401", "F403"]
-"src/xncml/generated/*.py" = ["D"]
+"src/xncml/generated/*.py" = ["D", "UP"]
 "src/xncml/parser.py" = ["C901"] # To be added
 "tests/**" = ["D100", "D101", "D102", "D103", "S101"]
 

src/xncml/generated/ncml_2_2.py

@@ -2,6 +2,7 @@
 
 from dataclasses import dataclass, field
 from enum import Enum
+from typing import Type
 
 __NAMESPACE__ = "http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2"
 
@@ -314,7 +315,7 @@ class Meta:
             "choices": (
                 {
                     "name": "enum",
-                    "type": type["EnumTypedef.EnumType"],
+                    "type": Type["EnumTypedef.EnumType"],
                 },
             ),
         },
@@ -475,7 +476,7 @@ class Meta:
                 },
                 {
                     "name": "group",
-                    "type": type["Group"],
+                    "type": Type["Group"],
                 },
                 {
                     "name": "remove",

src/xncml/parser.py

@@ -453,8 +453,8 @@ def read_enum(obj: EnumTypedef) -> dict[str, list]:
     dict:
         A dictionary describing the Enum.
 
-    Example
-    -------
+    Examples
+    --------
     .. code-block: xml
         <enumTypedef name="trilean" type="enum1">
             <enum key="0">false</enum>