search

deephaven / deephaven-plugins

Deephaven Plugins
11 stars 14 forks source link

Autodoc for autogenerating Plotly-express reference docs #501

Closed mofojed closed 3 months ago

mofojed commented 3 months ago

I have a branch where I was playing around with this for deephaven.ui: https://github.com/mofojed/deephaven-plugins/tree/341-example-consistency-apidoc/plugins/ui/sphinx-docs

Hook this up for deephaven-express/make it production ready.

Will need to have a source docs folder, and then a generated docs folder for the output (which deephaven.io should link to).

There was some talk of only keeping the sources in the repo, and then generated docs would be pushed/deployed to an S3 bucket (or something) but I don't think we're doing that yet @dsmmcken

dsmmcken commented 3 months ago

Yeah, actually I am ready to go a step further and try uploading it too.

Expectations around inserting something like this into our .md files

```{eval-rst}
autodocs(deeephaven.plot.express.scatter)
```

1, We have a source doc folder full of .md files + a sidebar.json

  1. markdown files contain 1 or more special instructions to insert an arg table like the above
  2. there's a build step that takes the source md, evaluates it and insert an arg table
  3. additional build steps may exists (as in this should be a script that could be part of a chain)
  4. The /build output is not committed
  5. There's a github action that calls the build steps and syncs the built files to cloudflare r2 into the appropriate path within the storage bucket: org/repo/project/version/ ex. /deephaven/deephaven-plugins/plotting/0.8/