jupyter-server-proxy icon indicating copy to clipboard operation
jupyter-server-proxy copied to clipboard

Automatically generate documentation for Server Process options

Open manics opened this issue 1 year ago • 3 comments

Currently the documentation for Server Process options and the documentation in the code comments is redundant:

https://github.com/jupyterhub/jupyter-server-proxy/blob/11fcf896129483a221135441ee50966025242b55/jupyter_server_proxy/config.py#L168-L283

https://github.com/jupyterhub/jupyter-server-proxy/blob/11fcf896129483a221135441ee50966025242b55/docs/source/server-process.md?plain=1#L20-L242

This PR builds on top of https://github.com/jupyterhub/jupyter-server-proxy/pull/507 to autogenerate the documentation using a custom Sphinx Directive.

manics avatar Oct 27 '24 17:10 manics

Instead of writing the custom extension, we could also use autodoc-traits, which does almost the same. The output looks almost identical.

jwindgassen avatar Nov 18 '24 09:11 jwindgassen

I tried autodoc traits originally, but it's not suitable for generating https://jupyter-server-proxy.readthedocs.io/en/latest/server-process.html because although the underlying class uses Traitlets in this particular context we're not configuring it using Traitlets. Instead we're using a dict which is converted to the Traitlets object.

manics avatar Nov 18 '24 15:11 manics

Is there any particular reason we do not want to use Union([Instance(ServerProcess), Dict()]) as the value for the dictionary? We could just add a small note to the docs, that it can be a dictionary as well with the same keys.

jwindgassen avatar Nov 18 '24 16:11 jwindgassen