Docs #28
Docs #28
Conversation
|
Suggested theme: https://github.com/pydata/pydata-sphinx-theme |
|
I am not totally conviced by pydata-sphinx-theme, would like to take input from more people. Here how it looks with light and dark modes: Here how readthedocs theme looks like for comparison:
pydata theme doesn't build a sidebar from independent toctree elements automatically (but gives more configurability like being able to set independent sidebars for different pages) and I find it less browsable (for a complete doc example I think NumPy is a good one: https://numpy.org/doc/1.24/reference/index.html), so before I invest more time into it, I want to know what is the consensus on preferred theme. Open to new suggestions as well. Please give input @mattersoflight , @talonchandler , @keithchev , @JoOkuma |
|
I'm mostly agnostic. readthedocs theme looks a bit more readable to me, but using pydata would be consistent w established packages like numpy and zarr, which iohub is obviously closely related to, and this might help establish trust w external users. |
|
A sidebar is indeed useful to navigate and discover documentation. I am happy with any theme that provides sidebar like in numpy docs. The screenshot of the pydata-sphinx-theme GitHub page does show a sidebar. |
|
Hi @AhmetCanSolak do you have a preference/plan for deployment? For example GH pages vs readthedocs, and build workflows. |
|
yes @ziw-liu , I am planning to host on gh pages and already have gh actions tasks to deploy |
|
given pydata/pydata-sphinx-theme#221 I will move with readthedocs theme, I think not sacrificing brows-ability is important to us at this stage. |
Thanks for looking into this. For now I'm happy with what gets us to the docs pages the fastest. |
AhmetCanSolak
requested review from
ziw-liu,
talonchandler,
ieivanov,
Christianfoley,
nbathreya and
mattersoflight
|
@AhmetCanSolak Can the documentation guidelines be added to |
.github/workflows/docs.yml
Outdated
| working-directory: ./docs | ||
| run: | | ||
| python -m pip install --upgrade pip | ||
| pip install -r requirements-docs.txt |
There was a problem hiding this comment.
this step should use pip install .'[doc]' since the build deps are specified in setup.cfg and not in docs/requirements-docs.txt. Also, this obviously means this step's working-directory should not be changed to docs/.
aside: it's obviously a bit inefficient to install the iohub package just to install the docs-build deps, but I think it's okay unless/until the package deps become unwieldy or complex (which hopefully never happens).
There was a problem hiding this comment.
great catch, addressed.
regarding your aside: AFAIK, it is actually required to install your package to utilize autosummary features the way we use with sphinx. Otherwise importing package submodules fails in different doc source files.
There was a problem hiding this comment.
That does make sense, but I know that the copylot docs workflow does not install the package, just the build deps, and it works (unless its docs don't use the autosummary features? I know nothing about sphinx...)
There was a problem hiding this comment.
Hmm I think this (ugly) line in the sphinx config might eliminate the need to install the package: sys.path.insert(0, os.path.abspath("../../"))
There was a problem hiding this comment.
I am not very welcoming to path manipulation idea :) but if majority agrees on it I can live with it.
There was a problem hiding this comment.
I mean, it's already in there, and it works, so I would vote for leaving it alone
|
Also, just for reference, after merging this PR we will need to make the following changes to the repo settings on github in order to allow the docs workflow to deploy the docs:
|
Just did it. |
|
Hi @AhmetCanSolak how can I locally build the docs and view? Do I need to setup a specific environment for documentation? |
Hi @mattersoflight, you can build locally following 42670af. |
|
|
@mattersoflight , I will merge this PR now but please provide your feedback whenever you can. I will make follow up PRs to address them. |
This PR introduces documentation page to
iohub.Description will be updated once draft status is removed from PR.Please see docs/README.md for usage, right now you can locally build these docs and test. Any feedback is welcome. Should something like this: