Skip to content

docs: Make autodoc output structured#582

Merged
mofojed merged 28 commits intodeephaven:mainfrom
jnumainville:501_structured_data
Jul 5, 2024
Merged

docs: Make autodoc output structured#582
mofojed merged 28 commits intodeephaven:mainfrom
jnumainville:501_structured_data

Conversation

@jnumainville
Copy link
Copy Markdown
Collaborator

Fixes #566

This adds a custom sphinx directive (dhautofunction) that takes the output of sphinx autofunction and extracts relevant data. Here is a snippet of the generated item in the area doc (in the doc it is all on one line)

<ParamTable param={{
  "module_name": "deephaven.plot.express.", 
  "name": "area", 
  "description": "Returns an area chart", 
  "parameters": [{"name": "table", "type": "Table | None", "description": "A table to pull data from.", "default": "None"}, ...], 
  "return_description": "A DeephavenFigure that contains the area chart", 
  "return_type": "DeephavenFigure"}}
 />

@jnumainville jnumainville requested review from dsmmcken and mofojed June 25, 2024 20:24
@jnumainville jnumainville self-assigned this Jun 25, 2024
@jnumainville jnumainville changed the title feat: Make autodoc output structured docs: Make autodoc output structured Jun 25, 2024
Comment thread .pre-commit-config.yaml Outdated
Comment thread plugins/plotly-express/make_docs.py Outdated
Comment thread sphinx_ext/.gitignore Outdated
Comment thread sphinx_ext/deephaven_autodoc.py Outdated
Comment thread plugins/plotly-express/make_docs.py Outdated
Comment thread plugins/plotly-express/requirements.txt
@dsmmcken
Copy link
Copy Markdown
Contributor

dsmmcken commented Jul 2, 2024

Are those keys constant?

Like is it always "module_name" or could that be different if it's not a module?

Note we could also write it as actual params rather then a dict, to remove wrapper if it's any easier.

<ParamTable name="name" description="..." params=[{...}] />

@jnumainville
Copy link
Copy Markdown
Collaborator Author

jnumainville commented Jul 3, 2024

module_name was just an alias I created for info extracted from the desc_addname node as it seems like it would generally be the module

all of the keys are constant otherwise, besides default in the params objects, which may or may not be there
from what I understand, these nodes, as weirdly structured as they are, do have some consistency. For example, the desc node Contains one or more desc_signature nodes and then a single desc_content node.

I don't think passing params directly would make anything easier on the extension side, but it could be done if it's preferable for the usage side

Copy link
Copy Markdown
Contributor

@dsmmcken dsmmcken left a comment

Choose a reason for hiding this comment

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

approving in that, it does what I need. Haven't reviewed any code, so that's on @mofojed

@mofojed mofojed merged commit d1aa3d5 into deephaven:main Jul 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Structured output for autodoc parameters (particularly for deephaven.ui)

3 participants