naming & directories

[tfiers]

This is part of my review of the already merged #2; so see there for context.

• Package name: spikeloc sounds good.
  I solved the described problem (descriptive package name vs not wanting to have a long name repeated lots in a notebook using it) in my own PhD project by using an import alias: import voltage_to_wiring_sim as v (and then v.simulate(…).
  You can then go as descriptive as you want (tab-completion in jupyter obsoletes typing long names in full).
  Maybe go all the way in descriptiveness with shared_code_for_comob_snn_soundloc_project? :p
  Instead of an import alias we can also go Brian-y and do from [our_package] import *, which is generally considered unpythonic, but for a jupyter notebook and homemade code with carefully curated automatic exports is fine. On the other hand, the big advantage of having namespaced objects is tab-completion: v.<tab>, and you get a list of the functions and types you can use. I.e. free api discoverability. (Has proved very useful, even if you wrote the package yourself!).

• Directory names:
  I propose naming the top level dir for shared code shared-code (or common-code,code, sth like that).
  Someone reading the directory names then knows what's what (notebooks, shared-code, web).
  The pyproject.toml / setup.py and package directory can then go inside that folder:

  code/
      spikeloc/
          __init__.py
          …
      pyproject.toml
  notebooks/
  web/
  …
  

  For notebooks/, I was thinking people can also contribute just markdown files
  instead of an .ipynb: JupyterBook builds these as well.
  (They extended the common markdown with cross-references, citations, etc: 'MyST').
  Use case I'm thinking of is e.g. someone doing a small lit review on a sub-topic.
  (We could even draft parts of the paper, or the whole thing, in .md files compiled by JupyterBook).
  Given that (namely that there's not only Jupyter Notebooks), maybe the dir name should change.
  (notes, work, output, research-morsels? :p). But notebooks/ is probably
  fine even when there's .mds in there.

[thesamovar]

Happy to use named and not * imports for this. For Brian we use * because we want to encourage absolute beginners, and because with lots of unit names it makes sense, but it's not the right approach here. I'm happy with spikeloc because I don't see it as being a heavily overloaded name, but still descriptive enough.

No strong feelings about directory structure so happy to go with @tfiers suggestion unless @synek or @ghoshm want to argue otherwise?

[rorybyrne]

I think it makes sense to name the directory something self-explanatory, and spikeloc might not be intuitive. But I don't want to break open-source conventions, so maybe src/ is a reasonable middle ground? That's already a common choice. Using spikeloc is more the "poetry style", and src/ is more the older "pip style". Since we're dropping poetry, we don't need to follow its convention!

Regarding setup.py inside the source directory, that pattern is usually indicative of a "monorepo", which is where an org has multiple projects sharing a single repository (e.g. for microservices or something). Seeing a meta-file at the top-level of a repository is one of the implicit cues that people pick up on when they first look at a repo (or at least it is for me, I'd be a bit confused if I didn't see a setup.py or pyproject.toml at top-level).

In general, I don't think we should break open source conventions to "make things easier" for people. One of the goals of this project (I assume) is that participants learn how to collaborate on Github, and that includes learning the conventions of open source. If we teach them that code goes into shared-code/ and setup.py goes inside the source directory, then they will be confused when they look at other open source projects which follow the normal conventions. If it ain't broke, don't fix it.

[thesamovar]

I still have no strong feelings!

[thesamovar]

My proposal is to just stick with what we already have because it's there and I'd like to make progress! OK with everyone?