Add: Tutorial for migrating from setup.py to pyproject.toml using Hatch

tutorials/get-to-know-hatch.md

@@ -139,7 +139,8 @@ and maintaining your Python package easier.
 
 A few features that hatch offers
 
-1. it will convert metadata stored in a `setup.py` or `setup.cfg` file to a pyproject.toml file for you. While we have not extensively tested this feature yet, please let us know if you try it!
+1. it will convert metadata stored in a `setup.py` or `setup.cfg` file to a pyproject.toml file for you (see [Migrating setup.py to pyproject.toml using Hatch](setup-py-to-pyproject-toml.md
+))
 2. It will help you by storing configuration information for publishing to PyPI after you've entered it once.
 
 Use `hatch -h` to see all of the available commands.

tutorials/installable-code.md

@@ -147,6 +147,17 @@ Neither 'setup.py' nor 'pyproject.toml' found.
 
 :::
 
+:::{admonition} Note about `setup.py`
+:class: tip
+
+If your project already defines a `setup.py` file, Hatch can be used to automatically create the `pyproject.toml`.
+* See [Using Hatch to Migrate setup.py to a pyproject.toml
+](setup-py-to-pyproject-toml.md)
+
+:::
+
+
+
 ## Time to create your Python package!
 
 Now that you understand the basics of the Python package directory structure, and associated key files (`__init__.py` and `pyproject.toml`), it's time to create your Python package!

tutorials/intro.md

@@ -29,6 +29,7 @@ understanding the steps involved in creating a Python package.
 :caption: Python Packaging Tutorial Setup
 
 Get to know Hatch <get-to-know-hatch>
+Migrate setup.py to a pyproject.toml using Hatch <setup-py-to-pyproject-toml>
 :::
 
 :::{toctree}

tutorials/setup-py-to-pyproject-toml.md

@@ -0,0 +1,105 @@
+# Using Hatch to Migrate setup.py to a pyproject.toml
+
+Hatch can be particularly useful to generate your project's `pyproject.toml` if your project already has a `setup.py`.
+
+:::{admonition} Note
+:class: tip
+
+This step is not necessary and is only useful if your project already has a `setup.py` file defined.
+* If your project does not already define a `setup.py` see [Make your Python code installable](installable-code.md)
+:::
+
+:::{admonition} Learning Objectives
+:class: tip
+
+In this lesson you will learn:
+
+1. The process of using Hatch to transition to using `pyproject.toml` for projects that already have a `setup.py` defined.
+:::
+
+## What is Hatch?
+
+Hatch is a Python package manager designed to streamline the process of creating, managing, and distributing Python packages. It provides a convenient CLI (Command-Line Interface) for tasks such as creating new projects, managing dependencies, building distributions, and publishing packages to repositories like PyPI.
+
+:::{admonition} Get to know Hatch
+:class: tip
+
+See [Get to know Hatch](get-to-know-hatch.md) for more information.
+
+:::
+
+## Prerequisites
+
+Before we begin, ensure that you have Hatch installed on your system. You can install it via pip:
+
+```bash
+pipx install hatch
+```
+
+## Sample Directory Tree
+
+Let's take a look at a sample directory tree structure before and after using `hatch init`:
+
+### Before `hatch init`
+
+```
+project/
+│
+├── src/
+│   └── my_package/
+│       ├── __init__.py
+│       └── module.py
+│
+├── tests/
+│   └── test_module.py
+│
+└── setup.py
+```
+
+### After `hatch init`
+
+```
+project/
+│
+├── pyproject.toml
+│
+├── src/
+│   └── my_package/
+│       ├── __init__.py
+│       └── module.py
+│
+├── tests/
+│   └── test_module.py
+│
+└── setup.py
+```
+
+As you can see, the main change after running `hatch init` is the addition of the `pyproject.toml` file in the project directory.
+
+## Step-by-Step Guide
+
+Now, let's walk through the steps to use Hatch to create a `pyproject.toml` file for your project.
+
+1. **Navigate to Your Project Directory**: Open your terminal or command prompt and navigate to the directory where your Python project is located.
+
+2. **Initialize Hatch**: Run the following command to initialize Hatch in your project directory:
+
+   ```bash
+   hatch new --init
+   ```
+
+3. **Review and Customize**: After running the previous command, Hatch will automatically generate a `pyproject.toml` file based on your existing project configuration. Take some time to review the contents of the generated `pyproject.toml` file. You may want to customize certain settings or dependencies based on your project's requirements (see [pyproject.toml tutorial](pyproject-toml.md) for more information about the `pyproject.toml`).
+
+4. **Verify**: Verify that the `pyproject.toml` file accurately reflects your project configuration and dependencies. You can manually edit the file if needed, but be cautious and ensure that the syntax is correct.
+
+5. **Delete setup.py**: Since we're migrating to using `pyproject.toml` exclusively, the `setup.py` file becomes unnecessary. You can safely delete it from your project directory.
+
+6. **Test Build**: Before proceeding further, it's essential to ensure that your project builds successfully using only the `pyproject.toml` file. Run the following command to build your project:
+
+```bash
+hatch build
+```
+
+This command will build your project based on the specifications in the `pyproject.toml` file. Make sure to check for any errors or warnings during the build process.
+
+7. **Test Existing Functionality**: After successfully building your project with `pyproject.toml`, it's crucial to ensure that your project's existing functionality remains intact. Run any pre-existing tests to verify that everything still works as expected.