jupyterhub / jupyter-server-proxy

Jupyter notebook server extension to proxy web services.
https://jupyter-server-proxy.readthedocs.io
BSD 3-Clause "New" or "Revised" License
354 stars 147 forks source link

Automatically generate documentation for Server Process options #508

Open manics opened 4 weeks ago

manics commented 4 weeks ago

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.

jwindgassen commented 6 days ago

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

manics commented 6 days ago

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.

jwindgassen commented 6 days ago

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.