Merge pull request #30 from openscm/fix-docs

Fix docs build

Author: znicholls

changelog/30.docs.md

@@ -0,0 +1 @@
+Fixed up the issues related to the docs rendering ([#29](https://github.com/openscm/pandas-openscm/issues/29)) and simplified the documentation of the accessors

changelog/30.trivial.md

@@ -0,0 +1 @@
+Removed the dependence on mkdocstrings-python-accessors for building the docs and upgraded to later versions of mkdocs related packages

docs/pandas-accessors.md

@@ -1,6 +1,6 @@
 # Pandas accessors
 
-Pandas-OpenSCM also provides a [pandas][] accessor.
+Pandas-OpenSCM also provides [pandas][] accessors.
 For details of the implementation of this pattern, see
 [pandas' docs](https://pandas.pydata.org/docs/development/extending.html#registering-custom-accessors).
 
@@ -10,8 +10,7 @@ which is a pattern we have had bad experiences with in the past).
 This is done with
 [register_pandas_accessors][pandas_openscm.accessors.register_pandas_accessors],
 
-By default, the accessors are provided under the "openscm" namespace
-and this is how the accessors are documented below.
+By default, the accessors are provided under the "openscm" namespace.
 However, the namespace can be customised when using
 [register_pandas_accessors][pandas_openscm.accessors.register_pandas_accessors],
 should you wish to use a different namespace for the accessor.
@@ -22,29 +21,41 @@ you will need to run something like:
 ```python
 from pandas_openscm.accessors import register_pandas_accessors
 
-# The 'pd.DataFrame.openscm' and 'pd.Series.openscm' namespace
+# The 'pd.DataFrame.openscm' and 'pd.Series.openscm' namespaces
 # will not be available at this point.
 
 # Register the accessors
 register_pandas_accessors()
 
-# The 'pd.DataFrame.openscm' and 'pd.Series.openscm' namespace
-# (or whatever other custom namespace you chose to register)
+# The 'pd.DataFrame.openscm' and 'pd.Series.openscm' namespaces
 # will now be available.
+# I.e. you could now do something like
+df = pd.DataFrame(
+    [
+        [1.1, 0.8, 1.2],
+        [2.1, np.nan, 8.4],
+    ],
+    columns=[2010.0, 2015.0, 2025.0],
+    index=pd.MultiIndex.from_tuples(
+        [
+            ("sa", "v2", "W"),
+            ("sb", "v2", "W"),
+        ],
+        names=["scenario", "variable", "unit"],
+    ),
+)
+
+# Use pandas-openscm's functionality via the registered accessors.
+df.openscm.to_long_data()
+
+# If you want to register the accessors under a custom namespace instead,
+# use something like the below instead
+register_pandas_accessors(namespace="my_custom_namespace")
+
+# Doing it this way will make the custom namespace available under
+# 'pd.DataFrame.my_custom_namespace' and 'pd.Series.my_custom_namespace'.
 ```
 
-The full accessor API is documented below.
-
-::: pandas_openscm.accessors.dataframe.PandasDataFrameOpenSCMAccessor
-    handler: python_accessors
-    options:
-        namespace: "pd.DataFrame.openscm"
-        show_root_full_path: false
-        show_root_heading: true
-
-::: pandas_openscm.accessors.series.PandasSeriesOpenSCMAccessor
-    handler: python_accessors
-    options:
-        namespace: "pd.Series.openscm"
-        show_root_full_path: false
-        show_root_heading: true
+The full accessor APIs are documented at
+[pandas_openscm.accessors.dataframe.PandasDataFrameOpenSCMAccessor][]
+and [pandas_openscm.accessors.series.PandasSeriesOpenSCMAccessor][].

mkdocs.yml

@@ -73,9 +73,9 @@ plugins:
       default_handler: python_xref
       enable_inventory: true
       handlers:
-        python_xref: &pythonhandleroptions
+        python_xref:
           paths: [src]
-          import:
+          inventories:
             # Cross-ref helpers (lots included here, remove what you don't want)
             - https://www.attrs.org/en/stable/objects.inv
             - https://unidata.github.io/cftime/objects.inv
@@ -110,8 +110,21 @@ plugins:
             - https://validators.readthedocs.io/en/stable/objects.inv
             - http://xarray.pydata.org/en/stable/objects.inv
           options:
+            # It turns out that xref does this check without considering config.
+            # As a result, every docstring is parsed as a google-style docstring.
+            # As docstrings are only parsed once, this results in rendering failures.
+            # Hence, turn off the checks here.
+            # mkdocs_autorefs catches anything which doesn't end up being a correct reference.
+            # The fix might be as simple as changing
+            # `self.collect(ref, PythonOptions())`
+            # to `self.collect(ref, self.get_options({}))`
+            # in the python-xref source, but it's hard to predict the side effects
+            # so we haven't bothered with that route.
+            check_crossrefs: false
             docstring_style: numpy
-            relative_crossrefs: yes
+            preload_modules:
+            - pint
+            relative_crossrefs: true
             separate_signature: true
             show_root_heading: false
             show_signature_annotations: true
@@ -122,7 +135,6 @@ plugins:
               classes: true
               functions: true
               modules: true
-        python_accessors: *pythonhandleroptions
   # https://squidfunk.github.io/mkdocs-material/plugins/search/
   - search
   # Add clickable sections to the sidebar

pyproject.toml

@@ -94,25 +94,24 @@ dev = [
 docs = [
     # Key dependencies
     # ----------------
-    "attrs==24.3.0",
-    "mkdocs-autorefs==1.2.0",
-    "mkdocs-gen-files==0.5.0",
-    "mkdocs-literate-nav==0.6.1",
-    "mkdocs-material==9.5.49",
-    "mkdocs-section-index==0.3.9",
-    "mkdocs==1.6.1",
-    "mkdocstrings-python-accessors>=0.1.1",
-    "mkdocstrings-python-xref==1.6.2",
-    "mkdocstrings-python==1.13.0",
-    "pymdown-extensions==10.13",
-    "ruff==0.8.6",
+    "attrs>=24.3.0",
+    "mkdocs-autorefs>=1.2.0",
+    "mkdocs-gen-files>=0.5.0",
+    "mkdocs-literate-nav>=0.6.1",
+    "mkdocs-material>=9.5.49",
+    "mkdocs-section-index>=0.3.9",
+    "mkdocs>=1.6.1",
+    "mkdocstrings-python-xref>=1.6.2",
+    "mkdocstrings-python>=1.13.0",
+    "pymdown-extensions>=10.13",
+    "ruff>=0.8.6",
     # Key dependencies for notebook_based_docs
     # ----------------------------------------
     "filelock>=3.16.1",
     "ipywidgets>=8.1.5",
-    "jupyterlab==4.3.4",
-    "jupytext==1.16.6",
-    "mkdocs-jupyter==0.25.1",
+    "jupyterlab>=4.3.4",
+    "jupytext>=1.16.6",
+    "mkdocs-jupyter>=0.25.1",
     "openscm-units>=0.6.3",
     "pandas-indexing>=0.6.2",
     "pint>=0.24.4",