Description
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)
- Add link to docs on right side of project -- this is one way to make sure people find the docs
- 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 😅 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)
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 🙂 Looking forward to see where you go with this!