-
Notifications
You must be signed in to change notification settings - Fork 33
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Swap docs to MkDocs #158
Merged
Swap docs to MkDocs #158
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
otherwise mkdocs won't properly document the property
(otherwise we're always overriding the alpha channel in RGBA colors)
plus some missed `` -> ` changes
- docstring - formatting - **kwargs parsing
- automatically map `cortex65/35` to most recent stack - no more hard-coded stacks/urls - new functions: get_datastacks, list_annotation_tables - use correct soma table - various other fixes
- fix deploy docs workflow - add flybrains to test requirements - download required transform; note: the transform is a heavily downsampled version of the real thing
- fix offset when axes are inverted - allow passing `scalebar` as a dictionary
Old and new tests are finally passing and I ticked off most TODOs. The workflow for building & deploying docs hasn't actually run yet because it is only triggered when pushing to the main branch (which makes sense, I guess). I'm guessing I forgot to add some of the I think at this point I will go ahead and merge. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR switches from Sphinx to MkDocs Material. A preview is already visible here: https://navis-org.github.io/navis/
Pretty happy with the results but there were a couple snags along the way:
With Sphinx we used NB convert to generated reST documents from the Jupyter notebooks. Here we switched to mkdocs-gallery - a port of Sphinx gallery - which uses
.py
Python scripts (with the# %%
cell syntax). Disadvantage: to get cell outputs (such as figures) we need to actually execute the script during the build. The issue with this is that (a) it takes a while (not too bad though) and (b) some example that e.g. need to download data or have a long run time (like the NBLASTs) had to be made static. Advantage: smaller file size and the build process effectively doubles as tests.mkdocs-gallery
works nice for the actual tutorials. For rendering other documents such as thequickstart.md
I usedmarkdown-exec
.Sphinx had the nice autodoc functions (e.g. the
:: autosummary
directive) which automatically generate the html files for the docstrings. With MkDocs we have to do a bit more leg work. I ended up usingmkdocs-gen-files
but I had to write a custom script to collect the functions (seegen_ref_pages2.py
). In addition, I usedmkdocs-macros-plugin
to write macro that lets me write e.g.{{ autosummary("navis.BaseNeuron.bbox") }}
(seemain.py
) to replace the Sphinx::autosummary
directive.Additional changes:
TreeNeuron.soma_pos
can now be set toNone
to remove any somanavis.Volume
now has a.units
property similar to neuronsneuprint.fetch_skeleton
from navis' neuprint interface to avoid confusion with our ownfetch_skeletons
(plural!)navis.screenshot()
(may bring that back later) - useViewer.screenshot
insteadNeuronList.__or__
magic methodNeuronList.get_neuron_attributes
navis.graph.skeleton_adjacency_matrix()
Neuron.pre/postsynapses
is now case-insensitive when looking for the respective connectortype
alpha
can now be given as a list/array with an alpha value for each neuronTreeNeuron.simple
where a soma could potentially lead to a non-branch, non-leaf node be retainedTODOs:
markdown-exec
to add some plots to quickstart (see this example; use# markdown-exec: hide
to hide lines of code)mkdocs-gallery
though (see Defining page setup in README.md smarie/mkdocs-gallery#96)