diff --git a/doc/English-manual.md b/doc/English-manual.md new file mode 100644 index 0000000..cf9f002 --- /dev/null +++ b/doc/English-manual.md @@ -0,0 +1,118 @@ +# 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 + +1. Navigate to the directory where `ProjectInitializerTool` is located. +2. Run the tool from your terminal using the Python module execution: + ```bash + 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) + +1. **Launch the GUI** as described above. +2. **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. +3. **Enter the Project Name:** + * Type the name for your new project in the "Project Name" field. + * Example: `MyNewUtility` +4. **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. +5. **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 + +1. Open your terminal or command prompt. +2. Navigate to the directory where `ProjectInitializerTool` is located. +3. Execute the tool with the required arguments: + ```bash + python -m project_initializer + ``` + * ``: The absolute or relative path to the directory where the new project folder will be created. + * ``: 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`: + +```bash +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! + + diff --git a/doc/Italian-manual.md b/doc/Italian-manual.md new file mode 100644 index 0000000..7446d0d --- /dev/null +++ b/doc/Italian-manual.md @@ -0,0 +1,116 @@ +# Project Initializer Tool - Manuale Italiano + +## 1. Introduzione + +Benvenuto nel Project Initializer Tool! Questa applicazione ti aiuta a configurare rapidamente una struttura di directory standardizzata e file di base essenziali per nuovi progetti Python, specialmente quelli destinati a essere gestiti con Git. + +Automatizza la creazione di cartelle comuni (come sorgente, documentazione, core, gui), file Python iniziali (`__init__.py`, `__main__.py`), un file `.gitignore`, un `README.md` di base, un template di file `.spec` per PyInstaller, e inizializza persino un repository Git locale. + +Lo strumento può essere utilizzato tramite una semplice Interfaccia Utente Grafica (GUI) o attraverso l'Interfaccia a Riga di Comando (CLI). + +## 2. Funzionalità + +* Crea una cartella principale per il progetto. +* Imposta una cartella annidata per il codice sorgente (es., `NomeProgetto/nomeprogetto_src/`). +* Genera una struttura di pacchetto Python standard all'interno della cartella sorgente: + * `nomeprogetto_src/core/__init__.py`, `nomeprogetto_src/core/core.py` + * `nomeprogetto_src/gui/__init__.py`, `nomeprogetto_src/gui/gui.py` + * `nomeprogetto_src/__init__.py`, `nomeprogetto_src/__main__.py` (configurato per essere eseguibile con `python -m nomeprogetto_src`) +* Crea una directory `doc/` con file template `English-manual.md` e `Italian-manual.md` per il nuovo progetto. +* Genera un file `README.md` di base per il nuovo progetto. +* Crea un template di file `.spec` per PyInstaller, configurato per il nuovo progetto. +* Copia un file icona predefinito `.ico` nel nuovo progetto. +* Crea un file `.gitignore` completo, adatto per progetti Python. +* Inizializza un repository Git locale nella directory principale del nuovo progetto ed esegue un commit iniziale. +* Supporta l'operatività sia tramite GUI (Tkinter) che CLI. +* Ricorda l'ultima directory radice utilizzata per la creazione di progetti (modalità GUI). + +## 3. Utilizzo dell'Interfaccia Utente Grafica (GUI) + +La GUI fornisce un modo interattivo per creare nuovi progetti. + +### 3.1. Avvio della GUI + +1. Naviga nella directory in cui si trova `ProjectInitializerTool`. +2. Esegui lo strumento dal tuo terminale utilizzando l'esecuzione del modulo Python: + ```bash + python -m project_initializer + ``` + (Assumendo che `project_initializer` sia il nome della cartella principale del pacchetto di questo strumento). + Questo aprirà la finestra "Project Initializer Tool". + +### 3.2. Componenti della GUI + +* **Directory Radice (Root Directory):** + * **Campo di Testo:** Visualizza il percorso della directory in cui verrà creata la cartella del tuo nuovo progetto. Questo campo sarà precompilato con l'ultima directory radice utilizzata, o la directory home del tuo utente al primo utilizzo. + * **Pulsante Sfoglia... (Browse...):** Clicca qui per aprire una finestra di dialogo e selezionare una directory radice diversa. +* **Nome Progetto (Project Name):** + * **Campo di Testo:** Inserisci il nome desiderato per il tuo nuovo progetto (es., "MiaAppFantastica", "AnalizzatoreDati"). Questo nome verrà utilizzato per la cartella principale del progetto. Una versione "sanificata" (minuscolo, underscore al posto di spazi/trattini) verrà usata per il nome del pacchetto sorgente interno. +* **Pulsante Crea Progetto (Create Project):** (Precedentemente "Procedi") Clicca questo pulsante dopo aver compilato la Directory Radice e il Nome Progetto per avviare il processo di creazione del progetto. + +### 3.3. Creazione di un Progetto (GUI) + +1. **Avvia la GUI** come descritto sopra. +2. **Imposta la Directory Radice:** + * Usa il percorso precompilato oppure clicca "Sfoglia..." per selezionare la directory genitore in cui vuoi che venga creata la cartella del tuo nuovo progetto. + * Esempio: Se selezioni `C:\Dev\ProgettiPython` come directory radice. +3. **Inserisci il Nome Progetto:** + * Digita il nome per il tuo nuovo progetto nel campo "Nome Progetto". + * Esempio: `MiaNuovaUtility` +4. **Clicca "Crea Progetto":** + * Lo strumento controllerà se una cartella con lo stesso nome progetto esiste già nella directory radice specificata. + * Se esiste, verrà visualizzato un messaggio di errore e il processo si interromperà. + * Se non esiste, lo strumento creerà l'intera struttura del progetto e i file come descritto nella sezione "Funzionalità". +5. **Feedback:** + * Messaggi verranno stampati sulla console (se visibile) che dettagliano ogni passo del processo di creazione. + * Una finestra di messaggio di successo o errore apparirà nella GUI al completamento o in caso di fallimento. + * In caso di successo, il campo "Nome Progetto" nella GUI verrà svuotato, pronto per inizializzare un altro progetto. La "Directory Radice" selezionata verrà ricordata per il prossimo utilizzo dello strumento. + +## 4. Utilizzo dell'Interfaccia a Riga di Comando (CLI) + +La CLI è utile per lo scripting o per gli utenti che preferiscono le operazioni da riga di comando. + +### 4.1. Avvio tramite CLI + +1. Apri il tuo terminale o prompt dei comandi. +2. Naviga nella directory in cui si trova `ProjectInitializerTool`. +3. Esegui lo strumento con gli argomenti richiesti: + ```bash + python -m project_initializer + ``` + * ``: Il percorso assoluto o relativo della directory in cui verrà creata la cartella del nuovo progetto. + * ``: Il nome desiderato per il tuo nuovo progetto. + +### 4.2. Argomenti CLI + +* **`root_directory` (Posizionale, Richiesto):** + * Specifica la directory genitore per il nuovo progetto. + * Esempio: `/home/utente/dev/python/` o `D:\Lavoro\MieiProgettiPython` +* **`project_name` (Posizionale, Richiesto):** + * Specifica il nome per la cartella del nuovo progetto. + * Esempio: `AppFiga`, `WebScraperV2` + +### 4.3. Creazione di un Progetto (CLI) - Esempio + +Per creare un nuovo progetto chiamato "ElaboratoreDati" all'interno della directory `/mnt/dati/progetti/progetti_python`: + +```bash +python -m project_initializer /mnt/dati/progetti/progetti_python ElaboratoreDati +``` + +**Output:** + +* Lo strumento stamperà messaggi sulla console che indicano l'avanzamento della creazione di directory e file, e l'inizializzazione di Git. +* Se la directory del progetto (`/mnt/dati/progetti/progetti_python/ElaboratoreDati`) esiste già, verrà stampato un messaggio di errore e lo script terminerà. +* Al completamento con successo, verrà visualizzato un messaggio di conferma. + +## 5. File di Configurazione + +Il Project Initializer Tool salva la propria configurazione (specificamente, l'ultima directory radice utilizzata per la GUI) in un file JSON chiamato `.project_initializer_config.json`. Questo file è memorizzato nella directory home del tuo utente. + +## 6. Note + +* **Icona Predefinita:** Lo strumento copia un file `default_icon.ico` nei nuovi progetti. Questa icona proviene dalla directory `project_initializer/assets/` all'interno del pacchetto stesso del Project Initializer Tool. Assicurati che questa icona esista se stai modificando lo strumento. +* **Requisito Git:** Affinché l'inizializzazione del repository Git funzioni, devi avere Git installato e accessibile nel PATH del tuo sistema. Se Git non viene trovato, la struttura del progetto verrà comunque creata, ma il repository Git non verrà inizializzato (verrà stampato un avviso). + +Grazie per aver utilizzato il Project Initializer Tool! \ No newline at end of file