Clean up the html docs for the dataframe API standard (#152)

* Update front page and sections

* Use autodoc better to generate dataframe and groupby docs

* More autodoc improvements, and cleaning up operator support boilerplate

* Finish dealing with operators on dataframes

* Fix last warnings, and include Column in the same way as DataFrame

* Upgrade Sphinx, sphinx-material and docutils

* Remove a few sentences with intra-markdown-file links

Resolves the issue with CI not being green due to a bug in Myst

Author: rgommers

requirements.txt

@@ -1,7 +1,7 @@
-sphinx==4.3.0
-sphinx-material==0.0.30
+sphinx==6.2.1
+sphinx-material==0.0.35
 myst-parser
 sphinx_markdown_tables
 sphinx_copybutton
-docutils<0.18
+docutils==0.19
 sphinx-math-dollar

spec/API_specification/column_object.rst

@@ -4,20 +4,9 @@ Column object
 =============
 
 A conforming implementation of the dataframe API standard must provide and
-support a column object having the following attributes and methods.
+support a column object having the following methods, attributes, and
+behavior.
 
--------------------------------------------------
-
-Methods
--------
-TODO
-
-..
-  NOTE: please keep the methods in alphabetical order
-
-    .. currentmodule:: dataframe_api
-
-    .. autosummary::
-       :toctree: generated
-   :template: property.rst
+.. currentmodule:: dataframe_api
 
+.. autoclass:: Column

spec/API_specification/dataframe_api/column_object.py

@@ -4,7 +4,19 @@
 
 from ._types import dtype
 
+
+__all__ = ['Column']
+
+
 class Column:
+    """
+    Column object
+
+    Note that this column object is not meant to be instantiated directly by
+    users of the library implementing the dataframe API standard. Rather, use
+    constructor functions or an already-created dataframe object retrieved via
+
+    """
     @classmethod
     def from_sequence(cls, sequence: Sequence[object], dtype: dtype) -> Column:
         """

spec/API_specification/dataframe_api/dataframe_object.py

@@ -11,6 +11,30 @@
 
 
 class DataFrame:
+    """
+    DataFrame object
+
+    Note that this dataframe object is not meant to be instantiated directly by
+    users of the library implementing the dataframe API standard. Rather, use
+    constructor functions or an already-created dataframe object retrieved via
+    
+    **Python operator support**
+
+    All arithmetic operators defined by the Python language, except for
+    ``__matmul__``, ``__neg__`` and ``__pos__``, must be supported for
+    numerical data types.
+
+    All comparison operators defined by the Python language must be supported
+    by the dataframe object for all data types for which those comparisons are
+    supported by the builtin scalar types corresponding to a data type.
+
+    In-place operators must not be supported. All operations on the dataframe
+    object are out-of-place.
+
+    **Methods and Attributes**
+
+    """
+
     @classmethod
     def from_dict(cls, data: Mapping[str, Column]) -> DataFrame:
         """

spec/API_specification/dataframe_api/groupby_object.py

@@ -4,7 +4,19 @@
     from .dataframe_object import DataFrame
 
 
+__all__ = ['GroupBy']
+
+
 class GroupBy:
+    """
+    GroupBy object.
+
+    Note that this class is not meant to be constructed by users.
+    It is returned from `DataFrame.groupby`.
+
+    **Methods**
+
+    """
     def any(self, skip_nulls: bool = True) -> "DataFrame":
         ...
 

spec/API_specification/dataframe_object.rst

@@ -4,169 +4,9 @@ Dataframe object
 ================
 
 A conforming implementation of the dataframe API standard must provide and
-support a dataframe object having the following attributes and methods.
-
--------------------------------------------------
-
-.. _operators:
-
-Operators
----------
-
-A conforming implementation of the dataframe API standard must provide and
-support a dataframe object supporting the following Python operators.
-
-Arithmetic Operators
-~~~~~~~~~~~~~~~~~~~~
-
-A conforming implementation of the array API standard must provide and support
-an array object supporting the following Python arithmetic operators.
-
--   `x1 + x2`: :meth:`.DataFrame.__add__`
-
-    -   `operator.add(x1, x2) <https://docs.python.org/3/library/operator.html#operator.add>`_
-    -   `operator.__add__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__add__>`_
-
--   `x1 - x2`: :meth:`.DataFrame.__sub__`
-
-    -   `operator.sub(x1, x2) <https://docs.python.org/3/library/operator.html#operator.sub>`_
-    -   `operator.__sub__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__sub__>`_
-
--   `x1 * x2`: :meth:`.DataFrame.__mul__`
-
-    -   `operator.mul(x1, x2) <https://docs.python.org/3/library/operator.html#operator.mul>`_
-    -   `operator.__mul__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__mul__>`_
-
--   `x1 / x2`: :meth:`.DataFrame.__truediv__`
-
-    -   `operator.truediv(x1,x2) <https://docs.python.org/3/library/operator.html#operator.truediv>`_
-    -   `operator.__truediv__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__truediv__>`_
-
--   `x1 // x2`: :meth:`.DataFrame.__floordiv__`
-
-    -   `operator.floordiv(x1, x2) <https://docs.python.org/3/library/operator.html#operator.floordiv>`_
-    -   `operator.__floordiv__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__floordiv__>`_
-
--   `x1 % x2`: :meth:`.DataFrame.__mod__`
-
-    -   `operator.mod(x1, x2) <https://docs.python.org/3/library/operator.html#operator.mod>`_
-    -   `operator.__mod__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__mod__>`_
-
--   `x1 ** x2`: :meth:`.DataFrame.__pow__`
-
-    -   `operator.pow(x1, x2) <https://docs.python.org/3/library/operator.html#operator.pow>`_
-    -   `operator.__pow__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__pow__>`_
-
-Arithmetic operators should be defined for a dataframe having real-valued data types.
-
-.. note::
-
-   TODO: figure out whether we want to add ``__neg__`` and ``__pos__``, those
-   are the two missing arithmetic operators.
-
-
-Comparison Operators
-~~~~~~~~~~~~~~~~~~~~
-
-A conforming implementation of the dataframe API standard must provide and
-support a dataframe object supporting the following Python comparison
-operators.
-
--   `x1 < x2`: :meth:`.DataFrame.__lt__`
-
-    -   `operator.lt(x1, x2) <https://docs.python.org/3/library/operator.html#operator.lt>`_
-    -   `operator.__lt__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__lt__>`_
-
--   `x1 <= x2`: :meth:`.DataFrame.__le__`
-
-    -   `operator.le(x1, x2) <https://docs.python.org/3/library/operator.html#operator.le>`_
-    -   `operator.__le__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__le__>`_
-
--   `x1 > x2`: :meth:`.DataFrame.__gt__`
-
-    -   `operator.gt(x1, x2) <https://docs.python.org/3/library/operator.html#operator.gt>`_
-    -   `operator.__gt__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__gt__>`_
-
--   `x1 >= x2`: :meth:`.DataFrame.__ge__`
-
-    -   `operator.ge(x1, x2) <https://docs.python.org/3/library/operator.html#operator.ge>`_
-    -   `operator.__ge__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__ge__>`_
-
--   `x1 == x2`: :meth:`.DataFrame.__eq__`
-
-    -   `operator.eq(x1, x2) <https://docs.python.org/3/library/operator.html#operator.eq>`_
-    -   `operator.__eq__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__eq__>`_
-
--   `x1 != x2`: :meth:`.DataFrame.__ne__`
-
-    -   `operator.ne(x1, x2) <https://docs.python.org/3/library/operator.html#operator.ne>`_
-    -   `operator.__ne__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__ne__>`_
-
-Comparison operators should be defined for dataframes having any data type.
-
-In-place Operators
-~~~~~~~~~~~~~~~~~~
-
-TODO
-
-Reflected Operators
-~~~~~~~~~~~~~~~~~~~
-
-TODO
-
-Arithmetic Operators
-""""""""""""""""""""
-
--   ``__radd__``
--   ``__rsub__``
--   ``__rmul__``
--   ``__rtruediv__``
--   ``__rfloordiv__``
--   ``__rpow__``
--   ``__rmod__``
-
--------------------------------------------------
+support a dataframe object having the following methods, attributes, and
+behavior.
 
 .. currentmodule:: dataframe_api
 
-Attributes
-----------
-
-TODO
-
-..
-  NOTE: please keep the attributes in alphabetical order
-
-
-..
- autosummary::
-   :toctree: generated
-   :template: property.rst
-
-   DataFrame.shape
-
--------------------------------------------------
-
-Methods
--------
-..
-  NOTE: please keep the methods in alphabetical order
-
-
-.. autosummary::
-   :toctree: generated
-   :template: property.rst
-
-   DataFrame.__add__
-   DataFrame.__eq__
-   DataFrame.__floordiv__
-   DataFrame.__ge__
-   DataFrame.__gt__
-   DataFrame.__le__
-   DataFrame.__lt__
-   DataFrame.__ne__
-   DataFrame.__mod__
-   DataFrame.__mul__
-   DataFrame.__pow__
-   DataFrame.__sub__
-   DataFrame.__truediv__
+.. autoclass:: DataFrame

spec/API_specification/groupby_object.rst

@@ -4,28 +4,10 @@ Groupby object
 ==============
 
 A conforming implementation of the dataframe API standard must provide and
-support a groupby object having the following attributes and methods.
-
--------------------------------------------------
-
-Methods
--------
-..
-  NOTE: please keep the methods in alphabetical order
+support a groupby object with the following API:
 
 .. currentmodule:: dataframe_api
 
-.. autosummary::
-   :toctree: generated
-   :template: property.rst
+.. autoclass:: GroupBy
+
 
-   GroupBy.all
-   GroupBy.any
-   GroupBy.max
-   GroupBy.min
-   GroupBy.mean
-   GroupBy.median
-   GroupBy.prod
-   GroupBy.std
-   GroupBy.sum
-   GroupBy.var

spec/API_specification/index.rst

@@ -4,7 +4,6 @@ API specification
 .. currentmodule:: dataframe_api
 
 .. toctree::
-   :caption: API specification
    :maxdepth: 3
 
    dataframe_object

spec/api_design_methodology.md

@@ -0,0 +1,3 @@
+# Methodology for API design
+
+TODO: describe approach used to construct the API.

spec/benchmark_suite.md

@@ -18,11 +18,11 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Python dataframe API standard'
-copyright = '2022, Consortium for Python Data API Standards'
+copyright = '2021-, Consortium for Python Data API Standards'
 author = 'Consortium for Python Data API Standards'
 
 # The full version, including alpha/beta/rc tags
-release = '2022.12-DRAFT'
+release = '2023.04-DRAFT'
 
 
 # -- General configuration ---------------------------------------------------
@@ -46,7 +46,15 @@
 
 autosummary_generate = True
 autodoc_typehints = 'signature'
+autodoc_default_options = {
+#    'attributes':       True,
+    'members':          True,
+    'special-members':  True,
+    'undoc-members':    True,
+    'exclude-members': '__annotations__, __dict__,__weakref__,__module__',
+}
 add_module_names = False
+napoleon_numpy_docstring = True
 napoleon_custom_sections = [('Returns', 'params_style')]
 default_role = 'code'
 

spec/conf.py

@@ -1,6 +1,14 @@
 Python dataframe API standard
 =============================
 
+.. note::
+
+   This API standard is still a work in progress, and approaching "minimum
+   viable product" status, where it's becoming possible to write library code
+   against it that is dataframe-agnostic. Design discussions are
+   happening in `this repository <https://github.com/data-apis/dataframe-api>`__.
+   Participation there is very much welcome.
+
 Contents
 --------
 
@@ -21,9 +29,8 @@ Contents
    API_specification/index
 
 .. toctree::
-   :caption: Methodology and Usage
+   :caption: Methodology and Tooling
    :maxdepth: 1
 
-   usage_data
+   api_design_methodology
    verification_test_suite
-   benchmark_suite