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.

Python Script Workspace con scheda Notes vuota associata al file main.py.
Figura 1. Schermata Notes iniziale relativa a main.py, prima di redigere il testo Markdown.

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.

Editor Notes con testo Markdown originale e risultato Rendered per il file main.py.
Figura 2. Una nota Markdown presenta il testo Source e l’anteprima Rendered affiancati.

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.

Vista Outline della nota Markdown con titoli Workflow e Limits.
Figura 3. La vista Outline raccoglie i titoli della nota per spostarsi rapidamente fra le sezioni.

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.

Pannello Notes Properties prima del primo Save, con informazioni di associazione al sorgente.
Figura 4. Properties mostra il rapporto fra la nota e il sorgente prima del primo salvataggio.

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.

Vista Resources dell’editor Markdown prima dell’aggiunta di risorse.
Figura 5. Resources è un pannello separato, qui vuoto perché non sono state inserite immagini.

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.

Codice Python High Contrast Dark visualizzato dopo la chiusura del pannello Notes.
Figura 6. Nascondere le note restituisce spazio alla sorgente Python senza modificarla.

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.

Scheda Notes di main.py riaperta con il testo Markdown non ancora salvato e indicatore di modifica.
Figura 7. Riaprendo la nota non salvata si recupera il testo di lavoro contrassegnato come modificato.

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.

Nota Markdown di main.py salvata, editor con contenuto originale e anteprima.
Figura 8. File → Save registra la nota di main.py, mantenendo separato il codice eseguibile.

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.
Testo Markdown di una nota distinta per helpers/calibration.py e Outline del modulo.
Figura 9. Una seconda scheda Notes documenta il modulo ausiliario helpers/calibration.py.

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.

Nota Markdown del file helpers/calibration.py salvata e distinta dalla nota principale.
Figura 10. File → Save All salva anche la nota del modulo ausiliario.

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.

Pannello Notes Properties con associazione current al file sorgente main.py.
Figura 11. Properties conferma che la nota principale è associata alla versione corrente di main.py.

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.

Editor GX-TXT High Contrast Dark con il codice del progetto visibile e pannello Notes nascosto.
Figura 12. Terminato il lavoro, si torna alla vista del codice Python con le note nascoste.

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.