Ideas for the site

[tlambert03]

Development topics

• [ ] Packaging (setuptools, hatch, poetry)
• [ ] Formatters (Black)
• [ ] Linters (ruff)
• [ ] Type checkers (mypy, pyright)
• [ ] Documentation (Sphinx, mkdocs)
• [ ] Testing (pytest, coverage)
• [ ] Code coverage (coverage.py)
• [ ] CI/CD (GitHub Actions)
• [ ] Version control (Git)
• [ ] Package versioning (__version__, setuptools_scm)
• [ ] Deployment (PyPI, conda-forge)
• [ ] Virtual environments (venv, pipenv, conda)
• [ ] Debugging (pdb, ipdb, pudb, ipdb, ptvsd)
• [ ] Profiling (cProfile, line_profiler, memory_profiler)
• [ ] Pre-commit hooks (pre-commit)
• [ ] Dependency management and pinning (libraries, applications)
• [ ] IDEs
• [ ] plugins and entry points?
• [ ] github pages

other ideas for site organization

• [ ] Get answers quick section
• [ ] In-depth answers section
• [ ] Tutorials?
• [ ] topic tags
• [ ] search
• [ ] "how to contribute" section
• [ ] "how to use this site" section?

misc

• [ ] cookiecutter/copier package (copy from https://github.com/tlambert03/pyrepo-copier)

[tlambert03]

cc @jdeschamps

[jdeschamps]

That looks awesome! We could potentially add the following:

Development tools

• [ ] Package structure: a separate section before the Packaging section, advocating for a particular package structure (src/) and describing briefly the main files (pyproject.toml, README.md, LICENSE, __init__.py etc.).
• [ ] Github pages: a do-it quick tutorial

Other ideas for site organization

• [ ] Further reading: section-dependent list of links (tutorials, guides, anything we think is a good read for whoever wants to dive further).

Sections like FAQ (quick answers), in-depth and further reading should be part of every "topical" section.

misc

• [ ] Example package: created from the copier package and including examples of everything that is discussed in the guide. All examples linked from the guide?
• [ ] Tutorials: lesser known (by scientists), yet useful, packages. We could also think of having small posts about things like "solving circular import", future annotations etc. One straight-forward tutorial is how to use the copy template. Another one is pydantic, the section in the guide that uses mypy could point to it.
• [ ] Essentials? : flash-card versions of the guide sections for quick look-up

[jdeschamps]

1 - Exhaustive vs opinionated guide

One stance to be discussed/validated here is whether to offer comparisons or proposals, the latter being similar to the "opinionated" guide we went through last time.

e.g.: The Packaging (setuptools, hatch, poetry) section could walk users through setting-up hatch, briefly highlighting why choosing it over the others, the quick answers would tell when to potentially prefer the others, the in-depth could dive further into the differences, and the Further reading point to examples of using setuptools and poetry.

The original idea was to have a guide offering easily digestible "wiki-how" solutions, as opposed to an encyclopedic approach. The latter being still possible through the in-depth sections.

I am putting this point here mostly to make it clear while this is out in the open. :)

2 - IDEs

While it makes sense to mention other IDEs in the relevant section, I would make this guide VSCode-dependent. That way we can offer direct walk-through of setting up the IDE (code navigation, code documentation, debugging, testing etc.).

If the VSCode dependent part is a subsection of each section, then non VSCode-users can easily skip it. Alternatively we could support both VSCode and PyCharm, but I would leave this out for now.

3 - Structure of the guide

Based on what you wrote in other ideas for site organization, here is quick proposal:

• Welcome page with how to use this site and how to contribute
• Guide:
  • intro
  • for each section:
    • intro
    • prepping VSCode (if applicable and possible in its own section)
    • how-to with examples (multiple subsections)
    • quick answers (FAQ)
    • in-depth
    • further reading
• Tutorials (if any)
• Essentials?
• Glossary (<- I like that)

[psobolewskiPhD]

I just want to chime in and say that this is setting up to be pure 🔥 🔥 🔥 Thank y'all! It already looks incredible and is super intuitive and easy to follow. 🙏 🙏

[tlambert03]

thanks @psobolewskiPhD :)

[jdeschamps]

Before starting to add more content to the tutorial, I wanted to give a go at making a rough plan. Based on what's in your first comment, here is a first draft:

• Bare minimum
• Summary of contents
• Virtual environment with conda
• Version control (git and Github)
• IDE (VSCode)
  • opening a project
  • useful settings (e.g. ruler line length 79)
  • in-built debugger
• Project metadata
  • Packaging tool (hatch)
    • what’s packaging
    • how to install a package
    • editable mode
  • Dependencies
  • Optional dependency groups
  • Tool specific settings (principle)
• Writing code
  • PEP8 conventions in brief
  • Code documentation (numpy docstring)
    • VSCode settings
  • typing
• Testing (pytest)
• Code quality tooling
  • Pre-commit hooks
  • Type checking (mypy)
  • Formatter (black)
  • Linter (ruff)
  • Code coverage (coverage.py)
  • pre-commit app
• CI/CD (Github actions)
  • Package versioning (hatch vcs)
  • Deployment (release, PyPi, conda)
  • Documentation deployment (Github pages)
• Package presentation
  • a good README
  • badges

What do you think? Changes and remarks welcome!

[tlambert03]

i think it looks awesome! thanks for diving in. ping me on #6 whenever you want. I think the most important thing at this point is to start getting words on pages, and we can iterate on the TOC structure forever. :)