Project Initializer Tool - English Manual

1. Introduction

Welcome to the Project Initializer Tool! This application helps you quickly set up a standardized directory structure and essential boilerplate files for new Python projects, especially those intended to be managed with Git.

It automates the creation of common folders (like source, documentation, core, gui), initial Python files (__init__.py, __main__.py), a .gitignore file, a basic README.md, a PyInstaller .spec file template, and even initializes a local Git repository.

The tool can be used via a simple Graphical User Interface (GUI) or through the Command Line Interface (CLI).

2. Features

Creates a main project folder.
Sets up a nested source code folder (e.g., ProjectName/projectname_src/).
Generates a standard Python package structure within the source folder:
- projectname_src/core/__init__.py, projectname_src/core/core.py
- projectname_src/gui/__init__.py, projectname_src/gui/gui.py
- projectname_src/__init__.py, projectname_src/__main__.py (configured to be executable with python -m projectname_src)
Creates a doc/ directory with template English-manual.md and Italian-manual.md files for the new project.
Generates a basic README.md file for the new project.
Creates a .spec file template for PyInstaller, configured for the new project.
Copies a default .ico icon file into the new project.
Creates a comprehensive .gitignore file suitable for Python projects.
Initializes a local Git repository in the new project's root directory and makes an initial commit.
Supports operation via both GUI (Tkinter) and CLI.
Remembers the last used root directory for project creation (GUI mode).

3. Using the Graphical User Interface (GUI)

The GUI provides an interactive way to create new projects.

3.1. Launching the GUI

Navigate to the directory where ProjectInitializerTool is located.
Run the tool from your terminal using the Python module execution:
```
python -m project_initializer
```
(Assuming project_initializer is the name of the main package folder of this tool). This will open the "Project Initializer Tool" window.

3.2. GUI Components

Root Directory:
- Text Field: Displays the path to the directory where your new project folder will be created. This field will be pre-filled with the last used root directory, or your user's home directory on first use.
- Browse... Button: Click this to open a dialog to select a different root directory.
Project Name:
- Text Field: Enter the desired name for your new project (e.g., "MyAwesomeApp", "DataAnalyzer"). This name will be used for the main project folder. A sanitized version (lowercase, underscores instead of spaces/hyphens) will be used for the internal source package name.
Create Project Button: (Previously "Proceed") Click this button after filling in the Root Directory and Project Name to start the project creation process.

3.3. Creating a Project (GUI)

Launch the GUI as described above.
Set the Root Directory:
- Either use the pre-filled path or click "Browse..." to select the parent directory where you want your new project folder to be created.
- Example: If you select C:\Dev\PythonProjects as the root directory.
Enter the Project Name:
- Type the name for your new project in the "Project Name" field.
- Example: MyNewUtility
Click "Create Project":
- The tool will check if a folder with the same project name already exists in the specified root directory.
  - If it exists, an error message will be displayed, and the process will stop.
  - If it does not exist, the tool will create the entire project structure and files as described in the "Features" section.
Feedback:
- Messages will be printed to the console (if visible) detailing each step of the creation process.
- A success or error message box will appear in the GUI upon completion or failure.
- If successful, the "Project Name" field in the GUI will be cleared, ready for you to initialize another project. The selected "Root Directory" will be remembered for the next time you use the tool.

4. Using the Command Line Interface (CLI)

The CLI is useful for scripting or for users who prefer command-line operations.

4.1. Launching via CLI

Open your terminal or command prompt.
Navigate to the directory where ProjectInitializerTool is located.
Execute the tool with the required arguments:
```
python -m project_initializer <root_directory> <ProjectName>
```
- <root_directory>: The absolute or relative path to the directory where the new project folder will be created.
- <ProjectName>: The desired name for your new project.

4.2. CLI Arguments

root_directory (Positional, Required):
- Specifies the parent directory for the new project.
- Example: /home/user/dev/python/ or D:\Work\MyPythonProjects
project_name (Positional, Required):
- Specifies the name for the new project folder.
- Example: CoolApp, WebScraperV2

4.3. Creating a Project (CLI) - Example

To create a new project named "DataProcessor" inside the directory /mnt/data/projects/python_projects:

python -m project_initializer /mnt/data/projects/python_projects DataProcessor

Output:

The tool will print messages to the console indicating the progress of directory and file creation, and Git initialization.
If the project directory (/mnt/data/projects/python_projects/DataProcessor) already exists, an error message will be printed, and the script will exit.
Upon successful creation, a confirmation message will be displayed.

5. Configuration File

The Project Initializer Tool saves its own configuration (specifically, the last used root directory for the GUI) in a JSON file named .project_initializer_config.json. This file is stored in your user's home directory.

6. Notes

Default Icon: The tool copies a default_icon.ico file into new projects. This icon is sourced from the project_initializer/assets/ directory within the Project Initializer Tool's own package. Ensure this icon exists if you are modifying the tool.
Git Requirement: For Git repository initialization to work, you must have Git installed and accessible in your system's PATH. If Git is not found, the project structure will still be created, but the Git repository will not be initialized (a warning will be printed).

Thank you for using the Project Initializer Tool!

6.6 KiB Raw Blame History