Source documentation/it: Difference between revisions

From FreeCAD Documentation
No edit summary
No edit summary
 
(27 intermediate revisions by the same user not shown)
Line 3: Line 3:
{{Docnav
{{Docnav
|[[Extra_python_modules/it|Moduli Python aggiuntivi]]
|[[Extra_python_modules/it|Moduli Python aggiuntivi]]
|[[Contributors/it|Contributors]]
|[[Contributors/it|Collaboratori]]
}}
}}


{{TOCright}}
{{TOCright}}


==Panoramica==
<div class="mw-translate-fuzzy">
Il codice sorgente di FreeCAD è commentato per consentire la generazione automatica della documentazione html con [http://www.doxygen.org Doxygen]. Questo vale sia per la parte C++ che per la parte Python del codice sorgente di FreeCAD.
Il codice sorgente di FreeCAD è commentato per consentire la generazione automatica della documentazione di programmazione utilizzando [[Doxygen/it|Doxygen]], un popolare sistema di documentazione del codice sorgente. Doxygen può documentare entrambe le parti C++ e Python di FreeCAD, ottenendo pagine HTML con collegamenti ipertestuali a ciascuna funzione e classe documentata.
</div>


La documentazione è online sul [https://freecad.github.io/SourceDoc/ sito web dell'API di FreeCAD]. Si prega di notare che questa documentazione potrebbe non essere sempre aggiornata; se c'è bisogno di maggiori dettagli, scaricare l'ultimo codice sorgente di FreeCAD e compilare da sé la documentazione. Se ci sono domande urgenti sul codice, chiedere nella sezione sviluppatori del [https://forum.freecadweb.org/index.php Forum di FreeCAD].
<div class="mw-translate-fuzzy">
La documentazione online del sorgente si trova in http://www.freecadweb.org/api/
</div>


Compiling the API documentation follows the same general steps as compiling the FreeCAD executable, as indicated in the [[Compile_on_Linux|Compile on Linux]] page.
La compilazione della documentazione dell'API segue gli stessi passaggi generali della compilazione dell'eseguibile di FreeCAD, come indicato nella pagina [[Compile_on_Linux/it|Compilazione in Linux]].


[[File:FreeCAD_documentation_compilation_workflow.svg|800px]]
[[File:FreeCAD_documentation_compilation_workflow.svg|800px]]


{{Caption|General workflow to compile FreeCAD's programming documentation. The Doxygen and Graphviz packages must be in the system, as well as the FreeCAD source code itself. CMake configures the system so that with a single make instruction the documentation for the the entire project is compiled into many HTML files with diagrams.}}
{{Caption|Flusso di lavoro generale per compilare la documentazione di programmazione di FreeCAD. I pacchetti Doxygen e Graphviz devono essere nel sistema, così come il codice sorgente di FreeCAD stesso. CMake configura il sistema in modo che con una singola istruzione make la documentazione per l'intero progetto venga compilata nei vari file HTML con i diagrammi.}}


<span id="Build_source_documentation"></span>
<span id="Build_source_documentation"></span>
== Costruire la documentazione del codice sorgente ==
== Costruire la documentazione del codice sorgente ==


<span id="Complete_documentation"></span>
=== Complete documentation ===
=== Documentazione completa ===


Se c'è installato Doxygen, è molto facile costruire la documentazione. Installare anche [https://www.graphviz.org/ Graphviz] per poter produrre diagrammi che mostrino le relazioni tra le diverse classi e le librerie nel codice di FreeCAD. Graphviz è utilizzato anche dal [[Std_DependencyGraph/it|grafico delle dipendenze]] di FreeCAD per mostrare le relazioni tra i diversi oggetti.
<div class="mw-translate-fuzzy">
Se Doxygen è già installato, è molto facile costruire il doc (la documentazione). Andare nella propria directory di compilazione di FreeCAD, configurare il sorgente con CMake, eseguendo
</div>
{{Code|code=
{{Code|code=
sudo apt install doxygen graphviz
sudo apt install doxygen graphviz
}}
}}


Then follow the same steps you would do to compile FreeCAD, as described on the [[Compile_on_Linux|compile on Linux]] page, and summarized here for convenience.
Quindi seguire gli stessi passi che si farebbero per compilare FreeCAD, come descritto nella pagina [[Compile_on_Linux/it|Compilazione in Linux]], e riassunti qui di seguito per comodità.
* Get the source code of FreeCAD and place it in its own directory {{incode|freecad-source}}.
* Prendere il codice sorgente di FreeCAD e metterlo nella sua directory {{incode|freecad-source}}.
* Create another directory {{incode|freecad-build}} in which you will compile FreeCAD and its documentation.
* Creare un'altra directory {{incode|freecad-build}} in cui si compilerà FreeCAD e la sua documentazione.
* Configure the sources with {{incode|cmake}}, making sure you indicate the source directory, and specify the required options for your build.
* Configurare i sorgenti con {{incode|cmake}}, assicurandosi di indicare la directory dei sorgenti, e specificare le opzioni richieste per la build.
* Trigger the creation of the documentation using {{incode|make}}.
* Attivare la creazione della documentazione usando {{incode|make}}.
{{Code|code=
{{Code|code=
git clone https://github.com/FreeCAD/FreeCAD.git freecad-source
git clone https://github.com/FreeCAD/FreeCAD.git freecad-source
Line 46: Line 42:
}}
}}


Mentre ci si trova all'interno della directory di build, dare le seguenti istruzioni per creare solo la documentazione.
While you are inside the build directory issue the following instruction to create only the documentation.
{{Code|code=
{{Code|code=
make -j$(nproc --ignore=2) DevDoc
make -j$(nproc --ignore=2) DevDoc
}}
}}
Come accennato in [[Compiling_(Speeding up)/it|velocizzare la compilazione]], l'opzione {{incode|-j}} imposta il numero di core della CPU utilizzati per la compilazione. I file di documentazione risultanti verranno visualizzati nella directory
<div class="mw-translate-fuzzy">
si possono consultare i file HTML risultanti iniziando da Doc/SourceDocu/html/index.html
</div>
{{Code|code=
{{Code|code=
freecad-build/doc/SourceDocu/html/
freecad-build/doc/SourceDocu/html/
}}
}}


The point of entrance to the documentation is the {{incode|index.html}} file, which you can open with a web browser:
Il punto di accesso alla documentazione è il file {{incode|index.html}}, che si può aprire con un browser web:
{{Code|code=
{{Code|code=
xdg-open freecad-build/doc/SourceDocu/html/index.html
xdg-open freecad-build/doc/SourceDocu/html/index.html
}}
}}


Il target {{incode|DevDoc}} genererà una notevole quantità di dati, circa 5 GB di nuovi file, in particolare grazie ai diagrammi creati da Graphviz.
<div class="mw-translate-fuzzy">
La DevDoc è molto ingombrante, se graphviz è installato sul sistema, genera un volume dei dati maggiore di 2Gb. Un'alternativa, può invece essere generata una versione più piccola (~ 500Mb), che è la versione utilizzata in http://www.freecadweb.org/api/ e che si ottiene con:
</div>


<span id="Reduced_documentation"></span>
=== Reduced documentation ===
=== Documentazione sintetica ===


The complete documentation uses around 3Gb of disk space. An alternative, smaller version of the documentation which takes only around 600 MB can be generated with a different target. This is the version displayed on the [https://freecad.github.io/SourceDoc/ FreeCAD API website].
La documentazione completa utilizza circa 3 GB di spazio su disco. Una versione alternativa e più piccola della documentazione che richiede solo circa 600 MB può essere generata con una destinazione diversa. Questa è la versione visualizzata sul [https://freecad.github.io/SourceDoc/ sito web dell'API di FreeCAD].
{{Code|code=
{{Code|code=
make -j$(nproc --ignore=2) WebDoc
make -j$(nproc --ignore=2) WebDoc
}}
}}


The documentation on the [https://freecad.github.io/SourceDoc/ FreeCAD API website] is produced automatically from https://github.com/FreeCAD/SourceDoc . Anyone can rebuild it and submit a pull request:
La documentazione sul [https://freecad.github.io/SourceDoc/ sito Web dell'API di FreeCAD] viene prodotta automaticamente da https://github.com/FreeCAD/SourceDoc. Chiunque può ricostruirla e inviare una richiesta di pull:


* Fork the repo at https://github.com/FreeCAD/SourceDoc
* Effettuare il fork del repository su https://github.com/FreeCAD/SourceDoc
* on your machine: clone the FreeCAD code (if you haven't yet), create a build dir for the doc, and clone the above SourceDoc repo inside. That SourceDoc will be updated when you rebuild the doc, and you'll be able to commit & push the results afterwards:
* sulla tua macchina: clonare il codice FreeCAD (se non è gia stato fatto), creare una build dir per il documento e clonare il suddetto repository SourceDoc all'interno. Quel SourceDoc verrà aggiornato quando si ricostruisce il documento e si sarà in grado di eseguire il commit ed inviare i risultati in seguito:
{{Code|code=
{{Code|code=
git clone https://github.com/FreeCAD/FreeCAD
git clone https://github.com/FreeCAD/FreeCAD
Line 92: Line 85:
git push
git push
}}
}}
* Go to your fork online, and create a pull request.
* Andare al fork online e creare una richiesta di pull.


== Altre versioni ==
<div class="mw-translate-fuzzy">
[https://iesensor.com/FreeCADDoc/0.19/ FreeCAD 0.19 development] documentazione creata da [http://forum.freecadweb.org/viewtopic.php?t=12613 qingfeng.xia].
In alternativa, la documentazione viene generata di volta in volta ed è accessibile su sourceforge [http://free-cad.sf.net/SrcDocu/index.html quí]
</div>


<span id="Integrate_Coin3D_documentation"></span>
<span id="Integrate_Coin3D_documentation"></span>
Line 104: Line 96:
Questo consente una navigazione più agevole e diagrammi di ereditarietà completi per le classi derivate da Coin.
Questo consente una navigazione più agevole e diagrammi di ereditarietà completi per le classi derivate da Coin.


*Installare il pacchetto {{incode|libcoin-doc}}, {{incode|libcoin80-doc}} o con nome simile.
<div class="mw-translate-fuzzy">
*Scompattare l'archivio {{incode|coin.tar.gz}} che si trova in {{incode|/usr/share/doc/libcoin-doc/html}}; i file potrebbero essere già decompressi nel sistema.
* Su Debian e sistemi derivati:
*Generare nuovamente la documentazione di origine.
: - Installare il pacchetto libcoin60-doc
: - Decomprimere il file /usr/share/doc/libcoin60-doc/html/coin.tag.gz
: - Rigenerare la documentazione del codice sorgente
: E si è pronti per navigare offline.
</div>


Se non si installa il pacchetto di documentazione per Coin, verranno generati i collegamenti per accedere alla documentazione online su [https://coin3d.bitbucket.io/Coin/ BitBucket]. Ciò accadrà se un file di tag Doxygen può essere scaricato al momento della configurazione con {{incode|wget}}.
<div class="mw-translate-fuzzy">
* Quando non si vuole o non si può installare il pacchetto della documentazione di Coin, vengono generati i collegamenti per accedere alla documentazione online di Coin in doc.coin3D.org se i file di tag doxygen possono essere scaricati al momento della configurazione (wget).
</div>


<span id="Using_Doxygen"></span>
<span id="Using_Doxygen"></span>
== Usare Doxygen ==
== Usare Doxygen ==


See the [[Doxygen|Doxygen]] page for an extensive explanation on how to comment C++ and Python source code so that it can be processed by Doxygen to automatically create the documentation.
Vedere la pagina [[Doxygen/it|Doxygen]] per un'ampia spiegazione su come commentare il codice sorgente C++ e Python in modo che possa essere elaborato da Doxygen per creare automaticamente la documentazione.


Essentially, a comment block, starting with {{incode|/**}} or {{incode|///}} for C++, or {{incode|##}} for Python, needs to appear before every class or function definition, so that it is picked up by Doxygen. Many [[Doxygen#Doxygen markup|special commands]], which start with {{incode|\}} or {{incode|@}}, can be used to define parts of the code and format the output. [[Doxygen#Markdown support|Markdown syntax]] is also understood within the comment block, which makes it convenient to emphasize certain parts of the documentation.
Essenzialmente, un blocco di commento, che inizia con {{incode|/**}} o {{incode|///}} per C++, o {{incode|##}} per Python, deve apparire prima di ogni classe o funzione definizione, in modo che venga raccolto da Doxygen. Molti [[Doxygen#Doxygen markup|comandi speciali]], che iniziano con {{incode|\}} o {{incode|@}}, possono essere usati per definire parti del codice e formattare l'output. La [[Doxygen#Supporto Markdown|Sintassi di Markdown]] funziona anche all'interno del blocco dei commenti, il che può essere utile per enfatizzare alcune parti della documentazione.
{{Code|code=
{{Code|code=
/**
/**
Line 138: Line 124:




{{Docnav
<div class="mw-translate-fuzzy">
{{docnav/it|[[Extra python modules/it|Moduli extra di Python]]|[[List of Commands/it|Elenco dei comandi]]}}
|[[Extra_python_modules/it|Moduli Python aggiuntivi]]
|[[Contributors/it|Collaboratori]]
</div>
}}


{{Userdocnavi{{#translation:}}}}
{{Userdocnavi{{#translation:}}}}

Latest revision as of 12:45, 22 April 2023

Panoramica

Il codice sorgente di FreeCAD è commentato per consentire la generazione automatica della documentazione di programmazione utilizzando Doxygen, un popolare sistema di documentazione del codice sorgente. Doxygen può documentare entrambe le parti C++ e Python di FreeCAD, ottenendo pagine HTML con collegamenti ipertestuali a ciascuna funzione e classe documentata.

La documentazione è online sul sito web dell'API di FreeCAD. Si prega di notare che questa documentazione potrebbe non essere sempre aggiornata; se c'è bisogno di maggiori dettagli, scaricare l'ultimo codice sorgente di FreeCAD e compilare da sé la documentazione. Se ci sono domande urgenti sul codice, chiedere nella sezione sviluppatori del Forum di FreeCAD.

La compilazione della documentazione dell'API segue gli stessi passaggi generali della compilazione dell'eseguibile di FreeCAD, come indicato nella pagina Compilazione in Linux.

Flusso di lavoro generale per compilare la documentazione di programmazione di FreeCAD. I pacchetti Doxygen e Graphviz devono essere nel sistema, così come il codice sorgente di FreeCAD stesso. CMake configura il sistema in modo che con una singola istruzione make la documentazione per l'intero progetto venga compilata nei vari file HTML con i diagrammi.

Costruire la documentazione del codice sorgente

Documentazione completa

Se c'è installato Doxygen, è molto facile costruire la documentazione. Installare anche Graphviz per poter produrre diagrammi che mostrino le relazioni tra le diverse classi e le librerie nel codice di FreeCAD. Graphviz è utilizzato anche dal grafico delle dipendenze di FreeCAD per mostrare le relazioni tra i diversi oggetti.

sudo apt install doxygen graphviz

Quindi seguire gli stessi passi che si farebbero per compilare FreeCAD, come descritto nella pagina Compilazione in Linux, e riassunti qui di seguito per comodità.

  • Prendere il codice sorgente di FreeCAD e metterlo nella sua directory freecad-source.
  • Creare un'altra directory freecad-build in cui si compilerà FreeCAD e la sua documentazione.
  • Configurare i sorgenti con cmake, assicurandosi di indicare la directory dei sorgenti, e specificare le opzioni richieste per la build.
  • Attivare la creazione della documentazione usando make.
git clone https://github.com/FreeCAD/FreeCAD.git freecad-source
mkdir freecad-build
cd freecad-build
cmake -DBUILD_QT5=ON -DPYTHON_EXECUTABLE=/usr/bin/python3 ../freecad-source

Mentre ci si trova all'interno della directory di build, dare le seguenti istruzioni per creare solo la documentazione.

make -j$(nproc --ignore=2) DevDoc

Come accennato in velocizzare la compilazione, l'opzione -j imposta il numero di core della CPU utilizzati per la compilazione. I file di documentazione risultanti verranno visualizzati nella directory

freecad-build/doc/SourceDocu/html/

Il punto di accesso alla documentazione è il file index.html, che si può aprire con un browser web:

xdg-open freecad-build/doc/SourceDocu/html/index.html

Il target DevDoc genererà una notevole quantità di dati, circa 5 GB di nuovi file, in particolare grazie ai diagrammi creati da Graphviz.

Documentazione sintetica

La documentazione completa utilizza circa 3 GB di spazio su disco. Una versione alternativa e più piccola della documentazione che richiede solo circa 600 MB può essere generata con una destinazione diversa. Questa è la versione visualizzata sul sito web dell'API di FreeCAD.

make -j$(nproc --ignore=2) WebDoc

La documentazione sul sito Web dell'API di FreeCAD viene prodotta automaticamente da https://github.com/FreeCAD/SourceDoc. Chiunque può ricostruirla e inviare una richiesta di pull:

  • Effettuare il fork del repository su https://github.com/FreeCAD/SourceDoc
  • sulla tua macchina: clonare il codice FreeCAD (se non è gia stato fatto), creare una build dir per il documento e clonare il suddetto repository SourceDoc all'interno. Quel SourceDoc verrà aggiornato quando si ricostruisce il documento e si sarà in grado di eseguire il commit ed inviare i risultati in seguito:
git clone https://github.com/FreeCAD/FreeCAD
cd FreeCAD
mkdir build
cd build
mkdir -p doc/SourceDocu/html
cd doc/SourceDocu/html
git clone your-fork-url
cd ../../..
cmake -DBUILD_QT5=ON -DPYTHON_EXECUTABLE=/usr/bin/python3 ..
make WebDoc
cd doc/SourceDocu/html
git commit
git push
  • Andare al fork online e creare una richiesta di pull.

Altre versioni

FreeCAD 0.19 development documentazione creata da qingfeng.xia.

Integrare la documentazione di Coin3D

Sui sistemi Unix, è possibile collegare la documentazione del codice sorgente di Coin3D con quella di FreeCAD. Questo consente una navigazione più agevole e diagrammi di ereditarietà completi per le classi derivate da Coin.

  • Installare il pacchetto libcoin-doc, libcoin80-doc o con nome simile.
  • Scompattare l'archivio coin.tar.gz che si trova in /usr/share/doc/libcoin-doc/html; i file potrebbero essere già decompressi nel sistema.
  • Generare nuovamente la documentazione di origine.

Se non si installa il pacchetto di documentazione per Coin, verranno generati i collegamenti per accedere alla documentazione online su BitBucket. Ciò accadrà se un file di tag Doxygen può essere scaricato al momento della configurazione con wget.

Usare Doxygen

Vedere la pagina Doxygen per un'ampia spiegazione su come commentare il codice sorgente C++ e Python in modo che possa essere elaborato da Doxygen per creare automaticamente la documentazione.

Essenzialmente, un blocco di commento, che inizia con /** o /// per C++, o ## per Python, deve apparire prima di ogni classe o funzione definizione, in modo che venga raccolto da Doxygen. Molti comandi speciali, che iniziano con \ o @, possono essere usati per definire parti del codice e formattare l'output. La Sintassi di Markdown funziona anche all'interno del blocco dei commenti, il che può essere utile per enfatizzare alcune parti della documentazione.

/**
 * Returns the name of the workbench object.
 */
std::string name() const;

/**
 * Set the name to the workbench object.
 */
void setName(const std::string&);

/// remove the added TaskWatcher
void removeTaskWatcher(void);