ezmsg-sigproc has basic documentation inside this repo. docs/source/extensions/sigproc.rst lists the individual modules in sigproc -- sphinx handles populating the modules with the code's docstrings.
If a new module is added to ezmsg-sigproc then we need to come back to this repo and add it to the docs, which is a weird workflow. Additionally, the docs/requirements.txt has to be maintained because the version of ezmsg-sigproc pulled in has to match the content of sigproc.rst. And what happens if the ezmsg-sigproc being pulled in has a different ezmsg dependency than the docs being built? It's a bit of a mess.
So, how do we fix this? And how do we do it more generally for other 1st party extensions (zmq, websockets, lsl, etc)?
I think it's inevitable that the extensions will need their own docs.
I've used intersphinx a bit in LSL to make it easier for the current docs to link to objects in another project's docs. e.g., ezmsg-sigproc's docs can link to ezmsg's AxisArray just as if they were in the same project, after the mapping is defined.
I don't mind creating the other reathedocs pages for the extensions if that's the solution we go with. I just want to open it up to other suggestions or complaints. For example, do we just create a ezmsg-org/docs mono repo? Is it a problem that in the proposed solution you can be navigating the API for ezmsg-sigproc and you click on a link and it brings you to a completely different docs page like base ezmsg?
(I encountered this recently. I was looking at the pynwb documentation and clicked on a link to the TimeSeries object and ended up in the hdmf documentation. It was seemless enough that I didn't notice, but then I was a bit confused when I looked at the navbar on the left expecting to find pynwb stuff.)
ezmsg-sigprochas basic documentation inside this repo.docs/source/extensions/sigproc.rstlists the individual modules in sigproc -- sphinx handles populating the modules with the code's docstrings.If a new module is added to ezmsg-sigproc then we need to come back to this repo and add it to the docs, which is a weird workflow. Additionally, the docs/requirements.txt has to be maintained because the version of ezmsg-sigproc pulled in has to match the content of
sigproc.rst. And what happens if the ezmsg-sigproc being pulled in has a differentezmsgdependency than the docs being built? It's a bit of a mess.So, how do we fix this? And how do we do it more generally for other 1st party extensions (zmq, websockets, lsl, etc)?
I think it's inevitable that the extensions will need their own docs.
I've used intersphinx a bit in LSL to make it easier for the current docs to link to objects in another project's docs. e.g., ezmsg-sigproc's docs can link to ezmsg's AxisArray just as if they were in the same project, after the mapping is defined.
I don't mind creating the other reathedocs pages for the extensions if that's the solution we go with. I just want to open it up to other suggestions or complaints. For example, do we just create a
ezmsg-org/docsmono repo? Is it a problem that in the proposed solution you can be navigating the API forezmsg-sigprocand you click on a link and it brings you to a completely different docs page like baseezmsg?(I encountered this recently. I was looking at the pynwb documentation and clicked on a link to the
TimeSeriesobject and ended up in the hdmf documentation. It was seemless enough that I didn't notice, but then I was a bit confused when I looked at the navbar on the left expecting to find pynwb stuff.)