GX-TXT Python Script Workspace: scrivere e conservare note Markdown per ogni file Python
Questa guida mostra come documentare un progetto Python direttamente nel Python Script Workspace di GX-TXT. Ogni file sorgente può avere una nota Markdown propria: è possibile scrivere il testo, consultarne l’anteprima, navigare fra i titoli, esaminare l’associazione con il codice e salvare separatamente la documentazione. Gli esempi utilizzano semplici funzioni su misure sintetiche: non eseguono il programma.
1. Perché associare una nota a un file Python
Una nota affianca al sorgente una spiegazione del suo scopo, delle variabili, delle ipotesi e delle limitazioni. È distinta dai commenti # presenti nel codice: i commenti rimangono nel programma, mentre la nota è un documento Markdown con titoli, elenchi, testo in evidenza e anteprima. Non è necessario modificare il codice per aggiornare la nota.
2. Situazione iniziale e prerequisiti
Aprire Python Script Workspace e un file .py già appartenente a uno Script o a un Project disponibile nel workspace. In questo esempio si usa un progetto con main.py come punto di ingresso e un modulo helpers/calibration.py. Per salvare note persistenti serve un contesto di lavoro autorizzato; la semplice apertura e modifica iniziale può precedere il salvataggio.
3. Tenere il codice leggibile
All’inizio conviene lasciare visibile soprattutto il sorgente Python. Explorer, Snippets, Debugger e altri pannelli non necessari possono rimanere chiusi. L’editor del codice usa il tema effettivo High Contrast Dark: non si tratta di una colorazione applicata alle immagini della guida.
4. Aprire la scheda Notes per main.py
Selezionare main.py e attivare Edit Notes dal controllo disponibile nel Workspace. Si apre la scheda delle note relativa al file scelto. In una nota nuova il documento è vuoto: ciò non significa che il file main.py sia vuoto o che il codice sia stato sostituito.

5. Identificare il documento e il sorgente associato
La scheda Notes riporta l’identità del file a cui è collegata. Quando si lavora su più file, controllare il nome della scheda prima di scrivere. La nota di main.py non è automaticamente la nota di un modulo importato.
6. Scrivere Markdown nella vista Source
La vista Source contiene il testo Markdown modificabile. Inserire titoli con # e ##, elenchi numerati con 1., parole evidenziate con **testo** e nomi di file o simboli Python fra accenti gravi. Qui Source indica la sorgente del documento Markdown, non il sorgente Python eseguibile.
7. Un esempio di nota riproducibile
Questo testo breve descrive il punto d’ingresso, l’import del modulo e i limiti dell’esempio. È una spiegazione: non contiene comandi da lanciare nel Runner.
# Calibration entrypoint
This note documents the Python project entrypoint.
Editing a note does not execute the source code.
## Workflow
1. Import `scale_readings` from `helpers.calibration`.
2. Apply a factor of **1.5** to synthetic measurements.
3. Keep `main.py` as the Project entrypoint.
## Limits
These values are illustrative. A scientific Job must be
started separately to produce a Dataset.
8. Confrontare Source e Rendered
La vista Rendered mostra il risultato leggibile del Markdown: le intestazioni diventano titoli, gli elenchi sono impaginati e il testo delimitato dagli accenti gravi appare distinto. Le viste possono essere mantenute affiancate per verificare subito il documento durante la scrittura.

9. Che cosa cambia nell’anteprima
In Rendered non si sta eseguendo né il Markdown né il codice Python citato. La vista interpreta soltanto la formattazione del documento. È utile per trovare un titolo scritto male, un elenco interrotto o un riferimento al modulo errato.
10. Aprire il pannello Outline
Nel menu View dell’editor Notes si può mostrare Outline. L’indice elenca i titoli riconosciuti nel documento e consente di orientarsi quando la nota cresce. Non crea sezioni nuove: riflette la struttura scritta in Source.

11. Esaminare la scheda Properties
Con View → Properties si visualizzano le informazioni della nota, inclusa l’associazione al file di origine quando disponibile. Prima del primo salvataggio non bisogna dedurre l’esistenza di un documento persistente dalla sola presenza del testo nell’editor.

12. Controllare Resources senza aggiungere immagini
La vista Resources è distinta da Source, Rendered, Outline e Properties. Nell’esempio iniziale è vuota perché non sono state ancora associate risorse. L’inserimento, la sostituzione e la rimozione di immagini sono trattati separatamente nella guida dedicata agli strumenti di formattazione e alle risorse.

13. Ripristinare un layout essenziale
Per leggere più comodamente, nascondere i pannelli Outline, Properties e Resources quando non servono. Il comando Reset note layout, dove presente nel menu View, ripristina la disposizione di base con Source e Rendered. È diverso dal reset generale del layout del Python Workspace.
14. Tornare al codice con Show Notes
Il comando che mostra o nasconde le note permette di ritornare al sorgente Python. Nascondere la vista non cancella il documento né trasforma il Markdown in codice. Dopo aver chiuso i pannelli facoltativi, lo spazio dell’editor torna utilizzabile per la programmazione.

15. Una nota modificata ma non ancora salvata
Durante la scrittura la scheda Notes può mostrare un indicatore di modifica, distinto dall’eventuale asterisco del file Python. Non confondere questi due stati: un documento Markdown modificato non significa che il codice .py sia stato alterato.
16. Nascondere e riaprire una bozza
È stato verificato che nascondere la nota e poi riaprirla nello stesso Workspace conserva il testo non salvato e la posizione di lavoro. Questo non sostituisce Save: se il documento deve sopravvivere alla chiusura del lavoro occorre salvarlo esplicitamente.

17. Salvare la nota principale
Con la nota di main.py attiva, utilizzare File → Save. Il documento passa da bozza modificata a nota salvata. L’operazione registra la nota Markdown nel contesto del progetto/sessione e la associa al file corrente. Il codice Python rimane separato.

18. Quale risultato viene registrato
Il contenuto della nota è conservato come documento Markdown canonico associato al sorgente. Nel caso di una Session, il salvataggio utilizza il sistema di registrazione dei dati di GX-TXT. Non va confuso con la pubblicazione di un Dataset numerico prodotto da un calcolo: nessun Job scientifico viene avviato da Save.
19. Note e revisione del progetto
Il salvataggio della nota può aggiornare la revisione dei metadati del Project. Ciò non equivale a una modifica del contenuto di main.py o di helpers/calibration.py. È importante distinguere la revisione del documento dalla versione effettiva degli algoritmi Python.
20. Aprire le note del file ausiliario
Ritornare all’albero dei file, selezionare helpers/calibration.py e aprire Edit Notes. Il Workspace crea o mostra una scheda Notes legata proprio a quel modulo. Una nota nuova del file ausiliario non eredita il Markdown già scritto per main.py.
21. Documentare la funzione del modulo
Per il modulo ausiliario si può usare una seconda nota concisa. Il riferimento alla funzione scale_readings(values, factor=1.5) serve a spiegare gli argomenti del codice, non a eseguirlo.
# Calibration helper
The file `helpers/calibration.py` defines
`scale_readings(values, factor=1.5)`.
## Purpose
- Process synthetic numeric measurements.
- Return a rounded Python list.
## Boundaries
This note describes the helper module, not the
`main.py` entrypoint. Saving is separate from execution.

22. Due note, due identità distinte
Le note di main.py e helpers/calibration.py sono due documenti differenti, pur appartenendo allo stesso Project. Controllare sempre file attivo, titolo della scheda Notes e testo prima di salvare. La struttura del progetto non cambia soltanto perché si descrivono più file.
23. Salvare dal comando Save All
Con una nota del modulo ausiliario modificata, File → Save All consente di registrare le modifiche pendenti dell’area di lavoro. Nella prova effettuata è stata salvata anche la seconda nota Markdown. Il comando non esegue il Python e non sostituisce la successiva revisione degli input del Runner.

24. Verificare Properties dopo Save
Riaprire la nota di main.py e consultare Properties. Per il file corrente si vede l’associazione valida con il sorgente: è un controllo utile dopo aver lavorato su più documenti. Una nota ancora modificata richiede invece Save prima di considerarla registrata.

25. Che cosa accade al sorgente Python
Scrivere o salvare una nota non cambia le istruzioni, le importazioni, l’entrypoint o la sequenza di calcolo dei file .py. Per aggiornare davvero un algoritmo, occorre ritornare alla relativa scheda Source Python, modificarlo e salvare il codice con la procedura prevista dal Workspace.
26. Terminare con l’editor sorgente
Quando la documentazione è completa, nascondere Notes e lasciare visibile il codice Python, evitando pannelli non necessari. Un progetto può quindi contenere il programma e le sue spiegazioni senza trasformare la finestra in un insieme permanente di schede affollate.

27. Limiti e controlli utili
Prima di chiudere il Viewer, verificare l’assenza di indicatori di modifica nelle note che si desidera conservare. Hide/Show Notes non è un salvataggio; Rendered non è un’esecuzione; Resources può essere vuoto; una nota associata non garantisce che il codice Python citato sia aggiornato o scientificamente corretto. Il dettaglio della gestione delle immagini è affrontato nella guida successiva.
28. Riepilogo operativo
Il percorso completo è: selezionare un file .py, aprire Edit Notes, scrivere in Source, controllare Rendered e Outline, consultare Properties e Resources solo quando utili, quindi Save o Save All. Ripetere sui singoli file del Project e infine tornare alla sorgente Python. Documentazione, metadati, codice eseguibile e Job restano concetti distinti.