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

Add Developer Documentation #1639

Merged
merged 31 commits into from
May 26, 2022
Merged

Conversation

thorstenhater
Copy link
Contributor

@thorstenhater thorstenhater commented Sep 2, 2021

Introduction

To onboard new devs we need to able to get them up to speed quickly.
Here's my (rough) proposal

  • Dev docs exist next to user docs, potentially touching similar topics.
  • In depth information on topic should be in the relevant (dev / user) part and cross-referenced.
  • Articles in doc/internal should be integrated into the developer part.
  • Dev docs should be structured analoguous to the data flow.

I start in this PR by adding an introductionary guide to cable cells. It outlines the flow
of cable cell simulations through arbor, sketches how cable cell simulations are set up,
and has jumping off points to more in depth topics.

TODO

  • Images
  • Backends
  • In-depth guides
    • mech-abi (can be migrated from internal)
    • backends
      • gpu
      • cpu (SIMD be migrated from internal)
    • shared state
    • event handling
    • solvers
    • discretisation
    • cell groups/super-cells/load balancing
  • Theory
    • cable equation (pull from cable_report.tex)
    • Numerical methods

@brenthuisman
Copy link
Contributor

I've added the script+css that can be used to generate diagrams. Preview on the Concepts>{index,recipe} pages: https://arbor-rtd-dev.readthedocs.io/en/latest/

Needs to be expanded to cover all Concepts pages that benefit from a visual representation of their context.

@brenthuisman brenthuisman modified the milestones: v0.6, v0.7 Feb 16, 2022
@brenthuisman brenthuisman linked an issue Feb 16, 2022 that may be closed by this pull request
Copy link
Contributor

@noraabiakar noraabiakar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a really good start, thanks a lot. I have a few comments and suggestions.

@noraabiakar noraabiakar self-assigned this Feb 21, 2022
Copy link
Contributor

@brenthuisman brenthuisman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • I've given the schematics a visual update (bit more compressed), made them foldable inplaces and moved them to more appropriate places.
  • internals merged into dev. I've hidden the numerical methods page for now, as it did not really contain anything. That OK?

@brenthuisman
Copy link
Contributor

  • Our beloved graphviz is back: a copy of the Arbor dep graph, and some more on a new Ecosystem page. Includes a list of all Arbor tools (such as nmlcc). Yes, not great, because graphviz and great plots are incompatible, but very helpful to have nonetheless.
  • Small change to bring some order to the tutorials as per Documentation: tutorial structure, howtos #1369.

Copy link
Contributor

@brenthuisman brenthuisman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The only change I'd want to put in here (besides corrections): dev/numerics.rst content and/or https://github.com/halfflat/arbor/tree/doc/update-model merged.

Possibly by using https://github.com/michael-brade/LaTeX.js

@brenthuisman
Copy link
Contributor

There is one last issue, I can't get RTD to generate the graphviz plots (which I'm certain I could a year ago or so).

…phs on ecosystem page. Add some more NMODL dialect hints.
@thorstenhater thorstenhater merged commit 8c85f00 into arbor-sim:master May 26, 2022
@thorstenhater thorstenhater deleted the doc/dev branch August 1, 2022 07:39
@brenthuisman brenthuisman modified the milestones: v0.7, v0.8 Aug 2, 2022
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.

AEP: Onboarding new developers: A guided tour of Arbor
6 participants