Welcome to Workflow Tutor

Warning

Please note that this repo is in Alpha state!

Motivation

This is a Hitchhiker's Guide to the Galaxy of Python projects. I am a medium level hobbyist, and I summarize and document my techniques, experiences, and decisions within Python projects in this Python project. It is not intended to be published as package. At best, it might be published from time to time on TestPyPI.

The toolchain chosen for my Python projects is:

  • Python, typ. >= 3.10 – who might have guessed it
  • Hatch as Python project management tool, which contains Click to design command line interfaces
  • MkDocs, including mkdocstrings for project documentation, of course also for Workflow Tutor
  • Git as version control system, and Codeberg as hub for the source code with issue tracking
  • PyPI as publication place (if it might ever happen)
  • Zed as »last next editor«
  • VSCodium, incl. the main plugins Python and Ruff
  • Alternatively micro, if in the TUI world

Further topics and tools might be added as they show up during my trip through the Galaxy!

Keep in mind...

This project is my personally biased overview of the topics, including a personal tool preference. You should be aware, that there are other tools and approaches, which might be a better choice for you. Workflow Tutor might help you, but it is far from being a tutorial, or an overview over one of the tools or topics covered.

The Python Packaging User Guide has Tool Recommendations.

I am always interested in bug hunting and improvements, I am not interested in any form of harassment. There is no absolutely best approach, and no absolutely best tool! I take the right to delete any of such aberrations without notice. On the other hand, any helpful contributions are very welcome.

Project Layout

The afore mentioned toolchain infers a certain folder and file structure, especially given by Hatch and MkDocs.

Main folders

.hatch/                 # Contains the virtual environments, organized via Hatch
docs/                   # Project documentation
pages/                  # Static HTML of the project documentation, excluded from »main« and any dev branches in Git
src/workflow-tutor/     # The projects source code
src/workflow-tutor/cli/ # Optional: The CLI of the project
tests/                  # The test environment

Main files

pyproject.toml          # Configuration file of the project, trying to avoid older approaches
mkdocs.yml              # The configuration file of MkDocs
README.md               # The Readme of a package, structure provided by Hatch
LICENSE.txt             # Typically Unlicense, do what you want to do with it, I do not care
dunder files under src/ # Structure given by Hatch
  • Writing your pyproject.toml - Overview of the configuration file from the Python Packaging User Guide
  • Awesome pyproject.toml - A list of projects considering or using pyproject.toml