pydev-guide/pydev-guide.github.io

Ideas for the site

Opened this issue · 7 comments

tlambert03 commented

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

jdeschamps commented

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 commented

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 commented

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.
🙏 🙏

  • ❤️2
tlambert03 commented

thanks @psobolewskiPhD :)

  • ❤️1
jdeschamps commented

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!

  • 👍1
  • ❤️1
tlambert03 commented

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. :)

  • 👍1