nwb-guide
nwb-guide copied to clipboard
NeurodataWithoutBorders
Add docs version switcher, favicon
Fix #759
- Add makefiles for easy local building
- Add favicon
- Copy logo into
docs/assets - Show logo to left of title in nav bar
- Add version switcher with
devand0.0.15 (stable)- see https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html - Update pydata-sphinx-theme version
- Update OS and python version of readthedocs build
Current:
New:
@CodyCBakerPhD @garrettmflynn IMHO, the default dropdown styling looks a bit ugly. I like pydantic docs' styling a bit better. Alternatively, we could move the version switcher to the top-right like pandas docs. What do you think?
Add makefiles for easy local building
Can you add instructions for this to the dev guide
IMHO, the default dropdown styling looks a bit ugly. I like pydantic docs' styling a bit better.
I'd go with Pydantic personally
0.0.15 (stable)
Will the stable move to latest official release?
Can you also explain how it is able to pin past version docs to how they would have looked at the time? Does RTD just keep those previous builds around at the original URLs?
Good questions!
Can you add instructions for this to the dev guide
Done
I'd go with Pydantic personally
I was mistaken. Pydantic doesn't use the Pydata Sphinx theme. We could still style our version switcher similarly by following https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html#style-the-switcher-buttons . @garrettmflynn I think you would be more efficient at styling this. Could you take a look?
Will the
stablemove to latest official release?
That is handled manually via docs/_static/switcher.json, unfortunately. We could try to automate it by generating that JSON on release? On build? But that might be a bit of a pain. I'm in favor of trying this out first to see if we even like having the version switcher.
Can you also explain how it is able to pin past version docs to how they would have looked at the time? Does RTD just keep those previous builds around at the original URLs?
I created a new automation rule in the ReadTheDocs settings for NWB GUIDE that activates the builds for any new tags that follow semantic versioning with or without a leading "v". (Our tags have been following semantic versioning with a leading "v", e.g., v0.0.15). I believe RTD keeps those previous builds around / can checkout a tag and build it.
Finally, I just enabled the version warning banner, so if you are on "dev", a banner will say: "This is documentation for an unstable development version. [Switch to stable version]". And if you are on an older version than the latest stable version (marked as "preferred" in that JSON), then the banner will say "This is documentation for an old version (x.y.z) [Switch to stable version]".
Currently RTD is configured to display latest by default when users go to nwb-guide.readthedocs.io. We could configure it to go stable instead (I believe stable automatically maps to the latest tag that follows semantic versioning / PEP 440 versioning rules, which accept an optional leading "v").
Something to try in a follow up after this is merged is to rebuild recent release versions (we have linux branches pinned to the commit points to leverage for this) so that when we use the main nav it doesn't lead us to a page without that same nav
That said I think if we go from dev to 0.0.15 for example, it might only see 0.0.14 and 0.0.13, right? So complete up to date nav isn't bidirectional?
I was mistaken. Pydantic doesn't use the Pydata Sphinx theme. We could still style our version switcher similarly by following https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html#style-the-switcher-buttons . @garrettmflynn I think you would be more efficient at styling this. Could you take a look?
I can figure something out. But since these are two different documentation frameworks, it'll take more than what the Pydata Sphinx documentation indicates.
What particular styling / behavior are we interested in replicating? Repositioning to cover the current selection is fairly simple, as is swapping the hover behavior and decoration. On the other hand, making the dropdown open/close on hover would need to be handled by some amount of JavaScript injection
What particular styling / behavior are we interested in replicating? Repositioning to cover the current selection is fairly simple, as is swapping the hover behavior and decoration. On the other hand, making the dropdown open/close on hover would need to be handled by some amount of JavaScript injection
IMO, more space to the left of the box, maybe 15-20px. Remove the border. Dropdown open/close on hover is not necessary. Super minor!
Something to try in a follow up after this is merged is to rebuild recent release versions (we have linux branches pinned to the commit points to leverage for this) so that when we use the main nav it doesn't lead us to a page without that same nav
After the next release, I think we do not need to keep showing docs for releases before the switcher, so this would not be necessary. Rebuilding an old release checks out the repo from the release, so to add the switcher, we would need to unrelease, commit on a branch, and re-release, which doesn't feel right. We can get around this by having docs for branches in addition to releases, but I think it's not necessary.
That said I think if we go from dev to 0.0.15 for example, it might only see 0.0.14 and 0.0.13, right? So complete up to date nav isn't bidirectional?
I'm not sure. The pydata sphinx theme website does not work that way, but I don't know how it would do that...
@garrettmflynn Did you know how to add that space Ryan asked for here?
If it's a hassle, I suggest we merge this PR sooner and optimize the styling later.
If it's a hassle, I suggest we merge this PR sooner and optimize the styling later.
Sounds good, raised https://github.com/NeurodataWithoutBorders/nwb-guide/issues/779