hatch icon indicating copy to clipboard operation
hatch copied to clipboard

Add tutorials showing how to start a new project using hatch

Open pfmoore opened this issue 8 months ago • 6 comments

The documentation is very focused on providing the technical details of how hatch works - in terms of the Diátaxis framework, reference information. But it's very hard to get started with hatch if you're unfamiliar with it. The addition of one or more "tutorial" style guides to the documentation, walking through the process of starting various types of projects with hatch, would be extremely helpful.

The obvious first example is a project that builds a library - this is already mentioned briefly in the introduction section, but it could be expanded, to discuss how a typical project development cycle would feel - adding code and tests, running the test suite, linting and formatting the project code, adding docs, type checking, etc. Specifically, of course, how hatch would be used for these tasks.

Going beyond that, it would be useful to have tutorials on other workflows such as data analysis. I'm picking this as an example because (a) it's familiar and important to me, (b) it has a very different workflow from building a library into a wheel, and (c) it's not well-supported by existing tools, so it's a great selling point if hatch does offer a good workflow for it. For this case, a basic workflow looks something like the following:

  1. Create a project directory and write your first data collection script. How would hatch be involved here? How would you run your script, and how would you manage dependencies?
  2. Add a new script to clean up the data - again, how would hatch be involved? The new script might have different dependencies than the first one. If you split out some shared code into a module that's imported by both scripts, how would you use hatch to manage the shared code?
  3. Add a Jupyter notebook for data exploration - how does hatch help in managing Jupyter, setting up an environment for running it, etc?
  4. Maybe extend the existing scripts to have a "proper" CLI, with some sort of shared config and unified option structure. At this point the project is growing into something more formal. Does hatch have any way of helping with this sort of large-scale refactoring?

I imagine this sort of workflow would make heavy use of hatch's environment features. What other features of hatch might be useful here, and how would you use them? Just to be clear here, I'm not talking about adding features to support this type of workflow. Rather I'm asking about documentation that explains how hatch as it currently stands works for that scenario. New features can be added to the tutorial when they get added to the tool, but the docs should be showing what it feels like to work with hatch right now.

The key point of these documents would be, for me, to give the reader a "feel" for what a familiar workflow would feel like when using hatch instead of whatever tools the user is currently using. What could hatch replace, what would need to be retained in support of hatch, and what benefits would come from using hatch? In isolation, there's no obvious advantage to running hatch fmt over black (assuming you have both hatch and black installed globally) so what's the compelling argument for switching?

pfmoore avatar Dec 12 '23 11:12 pfmoore