Skip to content

Render API docstrings in .py files as html #98

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Jan 18, 2023

Conversation

rgommers
Copy link
Member

This does the following:

  • Ensure the package in spec/API_specification/dataframe_api/ is importable
  • Ensure all docstrings for objects/methods are rendered in the html docs via autodoc
  • Add a description for operators supported by the dataframe object (and a few TODOs)
  • Adds Sphinx templates for styling the html rendered versions of methods and attributes properly (taken over from the array-api repo)
  • Adds some infrastructure for static typing that we may need. So far only the Scalar class needed a TypeVar, but there should be more to do there.

@rgommers rgommers added the documentation Improvements or additions to documentation label Jan 17, 2023
@rgommers rgommers requested a review from jbrockmendel January 17, 2023 09:02
The Sphinx templates help with better styling of methods/attrs
=============

A conforming implementation of the dataframe API standard must provide and
support a column object having the following attributes and methods.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should column be capitalized?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't do that on purpose. Maybe one thing to discuss in the context of constructors is whether the name matters (Column, DataFrame, etc.). For array libraries we left this out on purpose, because it's never needed and existing libraries name these things differently. The same could apply here, unless you allow calling object.__init__ as a constructor.

@jbrockmendel
Copy link
Contributor

a few nitpicks, otherwise looks fine

@rgommers
Copy link
Member Author

CI is happy and comments are addressed, so I'll go ahead and merge this.

@rgommers rgommers merged commit 60775db into data-apis:main Jan 18, 2023
@rgommers rgommers deleted the render-autodoc branch January 18, 2023 13:21
@rgommers
Copy link
Member Author

CI for deploying is happy, rendered docs are up on https://data-apis.org/dataframe-api/draft/API_specification/index.html.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants