Some suggestions to make TheLabbingProject packages more welcoming / accessible / citable

[NickleDave]

Hi @ZviBaratz good talking with you today!

I know you are very busy surviving writing up your thesis, but I did want to just share some suggestions based on what I saw when taking an initial look at the project.

I also know you've been really focused on writing up, so of course you haven't had as much time for maintenance and development as you'd like, and you probably are aware of many of these things.
But just in case it's helpful here's those suggestions:

apply to all TheLabbingProject repos

(I won't raise issues on each, just to be less annoying)

• [x] Add link to docs on right side of project -- this is one way to make sure people find the docs
• [x] Add "topics" here too: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics -- maybe not the single most impactful thing you can do but possibly helps with SEO and search on the site itself
• [ ] add DOIs from zenodo (on the to-do list I know)
• [ ] add citation.cff files! -- https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files
• [ ] move to pyproject.toml
• [ ] consider switching to a more "modern" theme, e.g. pydata-sphinx or furo https://github.com/pydata/pydata-sphinx-theme
• [ ] while you're at it, you might find it helpful to use myst: https://myst-parser.readthedocs.io/
• [ ] last but not least :sweat_smile: there's all the other stuff you'd want for a pyOS review: files like contributing.md, etc.
  • see https://www.pyopensci.org/python-package-guide/documentation/repository-files/intro.html
  • this is under active development but in general you want all the files listed there for any open source community-developed project
  • see also the guides there on fleshing out your README

specific to pylabber

• [ ] put more on index page of docs, i.e. the landing page?
  • like the schematic from overview
  • and immediately link to example apps like Django Analyses
  • could you maybe add another schematic that shows the Labbing Project "stack"?
  • since this is sort of the "base" for the whole project, you don't want to lose people here who are allergic to thinking about abstractions, so you should take this chance to hook them by saying "you can do these cool things with Pylabber (links)! Here's the beautiful design I have worked so hard to develop that makes it possible (read on if you're into that sort of thing...)"
  • personally, when the first thing I see on the landing page is a giant ToC then I find it really not helpful and kind of daunting. Not a criticism of you, it's the default mode for many Python docs, but I would highly recommend a different approach
  • See how I've set up the crowsetta docs here: https://crowsetta.readthedocs.io/en/latest/
  • Which are basically just a copy of what pandera and the pyGMT docs do (both pyOS packages)
  • https://pandera.readthedocs.io/en/stable/
  • https://www.pygmt.org/latest

Again I know you've been really focused on writing up. Just wanted to give you this feedback of what jumped out at me when I first started checking out the project. I think what you're doing has a lot of potential, just trying to help you not have to figure out some things I learned the hard way :slightly_smiling_face: Looking forward to see where you go with this!

[ZviBaratz]

Thank you so much! This is tremendously useful. Can't wait to submit my dissertation and start work on this.

I think some of the lower hanging fruit (e.g., documentation links, topic tags, etc.) I will do across packages, and then take more time to try and get django_dicom to be pyOS-compliant. The codebase has become somewhat large and requires some maintenance catch-ups (migrating to Django 4, increasing coverage, etc.), so it will be an incremental process. If that goes well, I'll continue to django_analyses, then django_mri, and finally pylabber.

[NickleDave]

Sounds like a plan to me :slightly_smiling_face:
Glad to give you something to look forward to on the other side of submitting :stuck_out_tongue: