You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.)
The text was updated successfully, but these errors were encountered:
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 differentezmsg
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 forezmsg-sigproc
and 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
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.)The text was updated successfully, but these errors were encountered: