Skip to content
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
merged 80 commits into from
Sep 6, 2024
Merged

Swap docs to MkDocs #158

merged 80 commits into from
Sep 6, 2024

Conversation

schlegelp
Copy link
Collaborator

@schlegelp schlegelp commented Sep 3, 2024

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:

  1. Tutorials:
    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 the quickstart.md I used markdown-exec.
  2. Autodocs
    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 using mkdocs-gen-files but I had to write a custom script to collect the functions (see gen_ref_pages2.py). In addition, I used mkdocs-macros-plugin to write macro that lets me write e.g. {{ autosummary("navis.BaseNeuron.bbox") }} (see main.py) to replace the Sphinx ::autosummary directive.

Additional changes:

  • TreeNeuron.soma_pos can now be set to None to remove any soma
  • navis.Volume now has a .units property similar to neurons
  • removed neuprint.fetch_skeleton from navis' neuprint interface to avoid confusion with our own fetch_skeletons (plural!)
  • removed navis.screenshot() (may bring that back later) - use Viewer.screenshot instead
  • implement NeuronList.__or__ magic method
  • new method: NeuronList.get_neuron_attributes
  • new function: navis.graph.skeleton_adjacency_matrix()
  • Neuron.pre/postsynapses is now case-insensitive when looking for the respective connectortype
  • plot2d/3d: alpha can now be given as a list/array with an alpha value for each neuron
  • fixed the MICrONs interface includes new functions and improvements
  • fixed a bug with TreeNeuron.simple where a soma could potentially lead to a non-branch, non-leaf node be retained
  • fixed a couple issues in plot2d and pl3d

TODOs:

  • add some missing gallery thumbnails
  • fix the ecosystem graphic
  • use markdown-exec to add some plots to quickstart (see this example; use # markdown-exec: hide to hide lines of code)
  • add tutorial for skeleton plotting
  • installation: move optional dependencies into a separate document?
  • add some eyecandy to landing page?
  • remove TOC from landing page?
  • edit the card icons on landing page
  • remove TOC from tutorials (should make them wider):
    ---
    hide:
      - navigation
      - toc
    ---
    
    This will require a fix in mkdocs-gallery though (see Defining page setup in README.md smarie/mkdocs-gallery#96)

otherwise mkdocs won't properly document the property
(otherwise we're always overriding the alpha channel in RGBA colors)
- 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
@schlegelp
Copy link
Collaborator Author

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 mkdocs plugins to the requirements but I will cross that bridge when we get there.

I think at this point I will go ahead and merge.

@schlegelp schlegelp marked this pull request as ready for review September 6, 2024 14:57
@schlegelp schlegelp merged commit 78f5423 into master Sep 6, 2024
21 checks passed
@schlegelp schlegelp deleted the mkdocs2 branch September 6, 2024 14:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants