Doxygen/it: Difference between revisions

From FreeCAD Documentation
(Created page with "Doxygen")
 
No edit summary
 
(136 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<languages/>
<languages/>


<span id="About"></span>
Doxygen is a popular tool for generating documentation from annotated C++ sources; it also supports other popular programming languages such as C#, PHP, Java, and Python. Visit the [http://www.doxygen.nl/ Doxygen website] to learn more about the system, and consult the [http://www.doxygen.nl/manual/index.html Doxygen Manual] for the full information.
==Introduzione==


{{TOCright}}
This document gives a brief introduction to Doxygen, in particular how it is used in FreeCAD to document its sources. Visit the [[source documentation|source documentation]] page for instructions on building the FreeCAD documentation, which is also hosted online on the [https://www.freecadweb.org/api/ FreeCAD API website].
Doxygen è uno strumento popolare per la generazione di documentazione da sorgenti C++ annotate; supporta anche altri linguaggi di programmazione popolari come C#, PHP, Java e Python. Visitare il [http://www.doxygen.nl/ sito web Doxygen] per saperne di più sul sistema e consultare il [http://www.doxygen.nl/manual/index.html Manuale Doxygen] per informazioni complete.

<span id="Doxygen_and_FreeCAD"></span>
== Doxygen e FreeCAD ==

Questo documento fornisce una breve introduzione a Doxygen, in particolare a come viene utilizzato in FreeCAD per documentarne i sorgenti. Visitare la pagina [[source documentation/it|documentazione del codice sorgente]] per istruzioni sulla creazione della documentazione di FreeCAD, anch'essa ospitata online sul [https://www.freecadweb.org/api/ sito web dell'API di FreeCAD].


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


{{Caption|General workflow to produce source code documentation with Doxygen.}}
{{Caption|Flusso di lavoro generale per produrre documentazione del codice sorgente con Doxygen.}}


<span id="Doxygen_with_C++_code"></span>
== Doxygen with C++ code ==
== Doxygen col codice C++ ==


The [http://www.doxygen.nl/manual/starting.html Getting started (Step 3)] section of the Doxygen manual mentions the basic ways of documenting the sources.
La sezione [http://www.doxygen.nl/manual/starting.html Getting started (Step 3)] del manuale Doxygen menziona i modi di base per documentare le fonti.


Per i membri, le classi e gli spazi dei nomi ci sono fondamentalmente due opzioni:
For members, classes and namespaces there are basically two options:
# Place a special "documentation block" (a commented paragraph) before the declaration or definition of the function, member, class or namespace. For file, class and namespace members (variables) it is also allowed to place the documentation directly after the member. See section [http://www.doxygen.nl/manual/docblocks.html#specialblock Special comment blocks] in the manual to learn more about these blocks.
# Posizionare uno speciale "blocco di documentazione" (un paragrafo commentato) prima della dichiarazione o della definizione della funzione, membro, classe o spazio dei nomi. Per i membri di file, delle classi e dello spazio dei nomi (variabili) è anche consentito posizionare la documentazione direttamente dopo il membro. Vedere la sezione [http://www.doxygen.nl/manual/docblocks.html#specialblock Blocchi di commenti speciali] nel manuale per saperne di più su questi blocchi.
# Place a special documentation block somewhere else (another file or another location in the same file) and put a "structural command" in the documentation block. A structural command links a documentation block to a certain entity that can be documented (a function, member, variable, class, namespace or file). See section [http://www.doxygen.nl/manual/docblocks.html#structuralcommands Documentation at other places] in the manual to learn more about structural commands.
# Posizionare un blocco di documentazione speciale da qualche altra parte (un altro file o un'altra posizione nello stesso file) e inserire un "comando strutturale" nel blocco di documentazione. Un comando strutturale collega un blocco di documentazione a una determinata entità che può essere documentata (una funzione, un membro, una variabile, una classe, uno spazio dei nomi o un file). Vedere la sezione [http://www.doxygen.nl/manual/docblocks.html#structuralcommands Documentazione in altri luoghi] ​​nel manuale per saperne di più sui comandi strutturali.


Nota:
Note:
*Il vantaggio della prima opzione è che non si deve ripetere il nome dell'entità (funzione, membro, variabile, classe o spazio dei nomi), poiché Doxygen analizzerà il codice ed estrarrà le informazioni rilevanti.
*The advantage of the first option is that you do not have to repeat the name of the entity (function, member, variable, class, or namespace), as Doxygen will analyze the code and extract the relevant information.
*I file possono essere documentati solo utilizzando la seconda opzione, poiché non è possibile inserire un blocco di documentazione prima di un file. Naturalmente, i membri del file (funzioni, variabili, typedef, define) non necessitano di un comando strutturale esplicito; semplicemente mettendo un blocco di documentazione prima o dopo di questi tutto funzionerà correttamente.
*Files can only be documented using the second option, since there is no way to put a documentation block before a file. Of course, file members (functions, variables, typedefs, defines) do not need an explicit structural command; just putting a documentation block before or after them will work fine.


<span id="First_style:_documentation_block_before_the_code"></span>
=== First style: documentation block before the code ===
=== Primo stile: blocco della documentazione prima del codice ===


Di solito si desidera documentare il codice nel file di intestazione, appena prima della dichiarazione di classe o del prototipo di funzione. Ciò mantiene la dichiarazione e la documentazione vicine l'una all'altra, quindi è facile aggiornare quest'ultima se la prima cambia.
Usually you'd want to document the code in the header file, just before the class declaration or function prototype. This keeps the declaration and documentation close to each other, so it's easy to update the latter one if the first one changes.


The special documentation block starts like a C-style comment {{incode|/*}} but has an additional asterisk, so {{incode|/**}}; the block ends with a matching {{incode|*/}}. An alternative is using C++-style comments {{incode|//}} with an additional slash, so {{incode|///}}.
Il blocco di documentazione speciale inizia come un commento in stile C {{incode|/*}} ma ha un asterisco aggiuntivo, quindi {{incode|/**}}; il blocco termina con un {{incode|*/}} corrispondente. Un'alternativa è utilizzare i commenti in stile C++ {{incode|//}} con una barra aggiuntiva, quindi {{incode|///}}.
{{Code|code=
{{Code|code=
/**
/**
Line 41: Line 50:
}}
}}


<span id="Second_style:_documentation_block_elsewhere"></span>
=== Second style: documentation block elsewhere ===
=== Secondo stile: blocco della documentazione altrove ===


In alternativa, la documentazione può essere collocata in un altro file (o nello stesso file in alto o in basso, o dovunque), lontano dalla dichiarazione di classe o dal prototipo di funzione. In questo caso, avrai informazioni duplicate, una volta nel file di origine effettivo e una volta nel file di documentazione.
Alternatively, the documentation can be placed in another file (or in the same file at the top or bottom, or wherever), away from the class declaration or function prototype. In this case, you will have duplicated information, once in the actual source file, and once in the documentation file.


First file, {{incode|source.h}}:
Primo file, {{incode|source.h}}:
{{Code|code=
{{Code|code=
std::string name() const;
std::string name() const;
Line 51: Line 61:
}}
}}


Second file, {{incode|source.h.dox}}:
Secondo file, {{incode|source.h.dox}}:
{{Code|code=
{{Code|code=
/** \file source.h
/** \file source.h
Line 67: Line 77:
}}
}}


In this case the structural command {{incode|\file}} is used to indicate which source file is being documented; a structural command {{incode|\fn}} indicates that the following code is a function, and the command {{incode|\brief}} is used to give a small description of this function.
In questo caso viene usato il comando strutturale {{incode|\file}} per indicare quale file sorgente si sta documentando; un comando strutturale {{incode|\fn}} indica che il seguente codice è una funzione, e il comando {{incode|\brief}} è usato per dare una breve descrizione di questa funzione.


This way of documenting a source file is useful if you just want to add documentation to your project without adding real code. When you place a comment block in a file with one of the following extensions {{incode|.dox}}, {{incode|.txt}}, or {{incode|.doc}} then Doxygen will parse the comments and build the appropriate documentation, but it will hide this auxiliary file from the file list.
Questo modalità di documentare un file sorgente è utile se vuoi solo aggiungere documentazione al tuo progetto senza aggiungere codice reale. Quando si inserisce un blocco di commento in un file con una delle seguenti estensioni {{incode|.dox}}, {{incode|.txt}} o {{incode|.doc}}, Doxygen analizzerà i commenti e creerà la documentazione appropriata, ma nasconderà questo file ausiliario dall'elenco dei file.


The FreeCAD project adds several files ending in {{incode|.dox}} in many directories in order to provide a description, or examples, of the code there. It is important that such files are correctly categorized in a group or namespace, for which Doxygen provides some auxiliary commands like {{incode|\defgroup}}, {{incode|\ingroup}}, and {{incode|\namespace}}.
Il progetto FreeCAD contiene diversi file che terminano con {{incode|.dox}} in molte cartelle per fornire una descrizione, o esempi, del codice presente. È importante che tali file siano correttamente categorizzati in un gruppo o in uno spazio dei nomi, per il quale Doxygen fornisce alcuni comandi ausiliari come {{incode|\defgroup}}, {{incode|\ingroup}} e {{incode|\namespace}} .


<div class="mw-collapsible mw-collapsed toccolours">
<div class="mw-collapsible mw-collapsed toccolours">
Example {{incode|src/Base/core-base.dox}}; this file in FreeCAD's source tree gives a short explanation of the {{incode|Base}} namespace.
Esempio {{incode|src/Base/core-base.dox}}; questo file nell'albero dei sorgenti di FreeCAD fornisce una breve spiegazione dello spazio dei nomi {{incode|Base}}.


<div class="mw-collapsible-content">
<div class="mw-collapsible-content">
Line 104: Line 114:
</div>
</div>


Another example is the file {{incode|src/Gui/Command.cpp}}. Before the implementation details of the {{incode|Gui::Command}} methods, there is a documentation block that explains some details of the command framework of FreeCAD. It has various {{incode|\section}} commands to structure the documentation. It even includes example code enclosed in a pair of {{incode|\code}} and {{incode|\endcode}} keywords; when the file is processed by Doxygen this code example will be specially formatted to stand out. The {{incode|\ref}} keyword is used in several places to create links to named sections, subsections, pages or anchors elsewhere in the documentation. Similarly, the {{incode|\see}} or {{incode|\sa}} commands print "See also" and provide a link to other classes, functions, methods, variables, files or URLs.
Un altro esempio è il file {{incode|src/Gui/Command.cpp}}. Prima dei dettagli di implementazione dei metodi {{incode|Gui::Command}}, c'è un blocco di documentazione che spiega alcuni dettagli del framework di comando di FreeCAD. Ha vari comandi {{incode|\section}} per strutturare la documentazione. Include anche codice di esempio racchiuso in una coppia di parole chiave {{incode|\code}} e {{incode|\endcode}}; quando il file viene elaborato da Doxygen, questo esempio di codice verrà appositamente formattato per distinguersi. La parola chiave {{incode|\ref}} viene utilizzata in diversi punti per creare collegamenti a sezioni, sottosezioni, pagine o ancore denominate altrove nella documentazione. Allo stesso modo, i comandi {{incode|\see}} o {{incode|\sa}} stampano "Vedi anche" e forniscono un collegamento ad altre classi, funzioni, metodi, variabili, file o URL.
<div class="mw-collapsible mw-collapsed toccolours">
<div class="mw-collapsible mw-collapsed toccolours">
Example {{incode|src/Gui/Command.cpp}}
Esempio {{incode|src/Gui/Command.cpp}}


<div class="mw-collapsible-content">
<div class="mw-collapsible-content">
Line 171: Line 181:
</div>
</div>


<span id="Example_from_the_VTK_project"></span>
=== Example from the VTK project ===
=== Esempio dal progetto VTK ===


This is an example from [https://vtk.org/ VTK], a 3D visualization library used to present scientific data, like finite element results, and point cloud information.
Questo è un esempio da [https://vtk.org/ VTK], una libreria di visualizzazione 3D utilizzata per presentare dati scientifici, come risultati di elementi finiti e informazioni come nuvola di punti.


A class to store a collection of coordinates is defined in a C++ header file. The top part of the file is commented, and a few keywords are used, like {{incode|@class}}, {{incode|@brief}}, and {{incode|@sa}} to indicate important parts. Inside the class, before the class method prototypes, a block of commented text explains what the function does, and its arguments.
Una classe per archiviare una raccolta di coordinate è definita in un file di intestazione C++. La parte superiore del file è commentata e vengono utilizzate alcune parole chiave, come {{incode|@class}}, {{incode|@brief}} e {{incode|@sa}} per indicare parti importanti. All'interno della classe, prima dei prototipi del metodo della classe, un blocco di testo commentato spiega cosa fa la funzione ei suoi argomenti.
* Source code of [https://github.com/Kitware/VTK/blob/master/Common/Core/vtkArrayCoordinates.h vtkArrayCoordinates.h].
* Codice sorgente di [https://github.com/Kitware/VTK/blob/master/Common/Core/vtkArrayCoordinates.h vtkArrayCoordinates.h].
* Doxygen produced documentation for the [http://www.vtk.org/doc/nightly/html/classvtkArrayCoordinates.html vtkArrayCoordinates class].
* Doxygen ha prodotto la documentazione per la [http://www.vtk.org/doc/nightly/html/classvtkArrayCoordinates.html classe vtkArrayCoordinates].


<span id="Compiling_the_documentation"></span>
== Compiling the documentation ==
== Compilazione della documentazione ==


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


{{Caption|General workflow to produce source code documentation with Doxygen.}}
{{Caption|Flusso di lavoro generale per produrre la documentazione del codice sorgente con Doxygen.}}


Per generare la documentazione del codice sorgente ci sono due passaggi fondamentali:
To generate the source code documentation there are two basic steps:
# Creare un file di configurazione per controllare come Doxygen elaborerà i file sorgente.
# Create a configuration file to control how Doxygen will process the source files.
# Run {{incode|doxygen}} on that configuration.
# Eseguire {{incode|doxygen}} su quella configurazione.


<div class="mw-collapsible mw-collapsed toccolours">
<div class="mw-collapsible mw-collapsed toccolours">
Il processo è descritto di seguito.
The process is described in the following.


<div class="mw-collapsible-content">
<div class="mw-collapsible-content">
* Make sure you have the programs {{incode|doxygen}} and {{incode|doxywizard}} in your system. It is also recommended to have the {{incode|dot}} program from [https://www.graphviz.org/ Graphviz], in order to generate diagrams with the relationships between classes and namespaces. On Linux systems these programs can be installed from your package manager.
* Assicurarsi di avere i programmi {{incode|doxygen}} e {{incode|doxywizard}} nel proprio sistema. Si consiglia inoltre di avere il programma {{incode|dot}} da [https://www.graphviz.org/ Graphviz], per generare diagrammi con le relazioni tra classi e spazi dei nomi. Sui sistemi Linux questi programmi possono essere installati dal tuo gestore di pacchetti.


{{Code|code=
{{Code|code=
sudo apt install doxygen doxygen-gui graphviz
sudo apt install doxygen doxygen-gui graphviz
}}
}}
* Assicurarsi di essere nella stessa cartella dei tuoi file di origine, o nella directory di livello superiore del tuo albero di origine, se si hanno molti file di origine in diverse sotto cartelle.
* Make sure you are in the same folder as your source files, or in the toplevel directory of your source tree, if you have many source files in different sub-directories.
{{Code|code=
{{Code|code=
cd toplevel-source
cd toplevel-source
}}
}}


* Run {{incode|doxygen -g DoxyDoc.cfg}} to create a configuration file named {{incode|DoxyDoc.cfg}}. If you omit this name, it will default to {{incode|Doxyfile}} without an extension.
* Eseguire {{incode|doxygen -g DoxyDoc.cfg}} per creare un file di configurazione chiamato {{incode|DoxyDoc.cfg}}. Se si omette questo nome, il valore predefinito sarà {{incode|Doxyfile}} senza estensione.
* This is a big, plain text file that includes many variables with their values. In the Doxygen manual these variables are called "tags". The configuration file and all tags are described extensively in the [http://www.doxygen.nl/manual/config.html Configuration] section of the manual. You can open the file with any text editor, and edit the value of each tag as necessary. In the same file you can read comments explaining each of the tags, and their default values.
* Questo è un grande file di testo semplice che include molte variabili con i loro valori. Nel manuale Doxygen queste variabili sono chiamate "tag". Il file di configurazione e tutti i tag sono ampiamente descritti nella sezione [http://www.doxygen.nl/manual/config.html Configurazione] del manuale. È possibile aprire il file con qualsiasi editor di testo e modificare il valore di ogni tag secondo necessità. Nello stesso file puoi leggere i commenti che spiegano ciascuno dei tag e i loro valori predefiniti.
{{Code|code=
{{Code|code=
DOXYFILE_ENCODING = UTF-8
DOXYFILE_ENCODING = UTF-8
Line 219: Line 231:
}}
}}


* Instead of using a text editor, you may launch {{incode|doxywizard}} to edit many tags at the same time. With this interface you may define many properties such as project information, type of output (HTML and LaTeX), use of Graphviz to create diagrams, warning messages to display, file patterns (extensions) to document or to exclude, input filters, optional headers and footers for the HTML generated pages, options for LaTeX, RTF, XML, or Docbook outputs, and many other options.
* Invece di utilizzare un editor di testo, si può avviare {{incode|doxywizard}} per modificare più tag contemporaneamente. Con questa interfaccia è possibile definire molte proprietà come informazioni sul progetto, tipo di output (HTML e LaTeX), utilizzo di Graphviz per creare diagrammi, messaggi di avviso da visualizzare, modelli di file (estensioni) da documentare o escludere, filtri di input, intestazioni opzionali e piè di pagina per le pagine generate in HTML, opzioni per output LaTeX, RTF, XML o Docbook e molte altre opzioni.
{{Code|code=
{{Code|code=
doxywizard DoxyDoc.cfg
doxywizard DoxyDoc.cfg
}}
}}


* Un'altra opzione è creare il file di configurazione da zero e aggiungere solo i tag desiderati con un editor di testo.
* Another option is to create the configuration file from scratch, and add only the tags that you want with a text editor.
* After the configuration is saved, you can run Doxygen on this configuration file.
* Dopo aver salvato la configurazione, si può eseguire Doxygen su questo file di configurazione.
{{Code|code=
{{Code|code=
doxygen DoxyDoc.cfg
doxygen DoxyDoc.cfg
}}
}}


* The generated documentation will be created inside a folder named {{incode|toplevel-source/html}}. It will consist of many HTML pages, PNG images for graphics, cascading style sheets ({{incode|.css}}), Javascript files ({{incode|.js}}), and potentially many sub-directories with more files depending on the size of your code. The point of entry into the documentation is {{incode|index.html}}, which you can open with a web browser.
* La documentazione generata verrà creata all'interno di una cartella denominata {{incode|toplevel-source/html}}. Consisterà in molte pagine HTML, immagini PNG per la grafica, fogli di stile a cascata ({{incode|.css}}), file Javascript ({{incode|.js}}) e potenzialmente molte sotto cartelle con più file a seconda sulla dimensione del codice. Il punto di accesso alla documentazione è {{incode|index.html}}, che si può aprire con un browser web.
{{Code|code=
{{Code|code=
xdg-open toplevel-source/html/index.html
xdg-open toplevel-source/html/index.html
Line 237: Line 249:
</div>
</div>


If you are writing new classes, functions or an entire new workbench, it is recommended that you run {{incode|doxygen}} periodically to see that the documentation blocks, [[#Markdown support|Markdown]], and [[#Doxygen markup|special commands]] are being read correctly, and that all public functions are fully documented. Please also read the [https://github.com/FreeCAD/FreeCAD/blob/master/src/Doc/doctips.dox documentation tips] located in the source code.
Se si stanno scrivendo nuove classi, funzioni o un intero nuovo workbench, si consiglia di eseguire periodicamente {{incode|doxygen}} per verificare che la documentazione blocchi [[#Markdown support|Markdown]] e [[#Doxygen markup|special commands]] vengano letti correttamente e che tutte le funzioni pubbliche siano completamente documentate. Si prega di leggere anche i [https://github.com/FreeCAD/FreeCAD/blob/master/src/Doc/doctips.dox suggerimenti per la documentazione] che si trovano nel codice sorgente.


When generating the complete FreeCAD documentation, you don't run {{incode|doxygen}} directly. Instead, the project uses {{incode|cmake}} to configure the build environment, and then {{incode|make}} triggers compilation of the FreeCAD sources and of the Doxygen documentation; this is explained in the [[source documentation|source documentation]] page.
Quando si genera la documentazione completa di FreeCAD, non si esegue {{incode|doxygen}} direttamente. Invece, il progetto utilizza {{incode|cmake}} per configurare l'ambiente di compilazione, quindi {{incode|make}} avvia la compilazione dei sorgenti di FreeCAD e della documentazione di Doxygen; questo è spiegato nella pagina [[source_documentation/it|documentazione sorgente]].


<span id="Doxygen_markup"></span>
== Doxygen markup ==
== markup di Doxygen ==


All Doxygen [http://www.doxygen.nl/manual/commands.html documentation commands] start with a backslash {{incode|\}} or an at-symbol {{incode|@}}, at your preference. Normally the backslash {{incode|\}} is used, but occasionally the {{incode|@}} is used to improve readability.
Tutti i [http://www.doxygen.nl/manual/commands.html comandi di documentazione] di Doxygen iniziano con una barra rovesciata {{incode|\}} o un simbolo at {{incode|@}}, a scelta. Normalmente si usa la barra rovesciata {{incode|\}}, ma occasionalmente si usa {{incode|@}} per migliorare la leggibilità.


I comandi possono avere uno o più argomenti. Nel manuale Doxygen gli argomenti sono descritti come segue.
The commands can have one or more arguments. In the Doxygen manual the arguments are described as follows.
* If {{incode|<sharp>}} braces are used the argument is a single word.
* Se vengono utilizzate parentesi con segno minore e maggiore {{incode|<sharp>}} l'argomento è una singola parola.
* If {{incode|(round)}} braces are used the argument extends until the end of the line on which the command was found.
* Se vengono utilizzate parentesi tonde {{incode|(round)}} l'argomento si estende fino alla fine della riga in cui è stato trovato il comando.
* Se vengono utilizzate le parentesi graffe <code>{curly}</code> l'argomento si estende fino al paragrafo successivo. I paragrafi sono delimitati da una riga vuota o da un indicatore di sezione.
* If <code>{curly}</code> braces are used the argument extends until the next paragraph. Paragraphs are delimited by a blank line or by a section indicator.
* If {{incode|[square]}} brackets are used the argument is optional.
* Se si usano le parentesi quadre {{incode|[square]}} l'argomento è facoltativo.


<div class="mw-collapsible mw-collapsed toccolours">
<div class="mw-collapsible mw-collapsed toccolours">
Alcune delle parole chiave più comuni utilizzate nella documentazione di FreeCAD sono presentate qui.
Some of the most common keywords used in the FreeCAD documentation are presented here.
<div class="mw-collapsible-content">
<div class="mw-collapsible-content">
* <code>\defgroup <name> (group title) </code>, see [http://www.doxygen.nl/manual/commands.html#cmddefgroup \defgroup], and [http://www.doxygen.nl/manual/grouping.html Grouping].
* <code>\defgroup <name> (group title) </code>, vedere [http://www.doxygen.nl/manual/commands.html#cmddefgroup \defgroup], e [http://www.doxygen.nl/manual/grouping.html Grouping].
* <code>\ingroup (<groupname> [<groupname> <groupname>])</code>, see [http://www.doxygen.nl/manual/commands.html#cmdingroup \ingroup], and [http://www.doxygen.nl/manual/grouping.html Grouping].
* <code>\ingroup (<groupname> [<groupname> <groupname>])</code>, vedere [http://www.doxygen.nl/manual/commands.html#cmdingroup \ingroup], e [http://www.doxygen.nl/manual/grouping.html Grouping].
* <code>\addtogroup <name> [(title)]</code>, see [http://www.doxygen.nl/manual/commands.html#cmdaddtogroup \addtogroup], and [http://www.doxygen.nl/manual/grouping.html Grouping].
* <code>\addtogroup <name> [(title)]</code>, vedere [http://www.doxygen.nl/manual/commands.html#cmdaddtogroup \addtogroup], e [http://www.doxygen.nl/manual/grouping.html Grouping].
* <code>\author { list of authors }</code>, see [http://www.doxygen.nl/manual/commands.html#cmdauthor \author]; indicates the author of this piece of code.
* <code>\author { list of authors }</code>, vedere [http://www.doxygen.nl/manual/commands.html#cmdauthor \author]; indica l'autore di questo pezzo di codice.
* <code>\brief { brief description }</code>, see [http://www.doxygen.nl/manual/commands.html#cmdbrief \brief]; briefly describes the function.
* <code>\brief { brief description }</code>, vedere [http://www.doxygen.nl/manual/commands.html#cmdbrief \brief]; descrive brevemente la funzione.
* <code>\file [<name>]</code>, see [http://www.doxygen.nl/manual/commands.html#cmdfile \file]; documents a source or header file.
* <code>\file [<name>]</code>, vedere [http://www.doxygen.nl/manual/commands.html#cmdfile \file]; documenta un file di origine o di intestazione.
* <code>\page <name> (title)</code>, see [http://www.doxygen.nl/manual/commands.html#cmdpage \page]; puts the information in a separate page, not directly related to one specific class, file or member.
* <code>\page <name> (title)</code>, see [http://www.doxygen.nl/manual/commands.html#cmdpage \page]; inserisce le informazioni in una pagina separata, non direttamente correlata a una specifica classe, file o membro.
* <code>\package <name></code>, see [http://www.doxygen.nl/manual/commands.html#cmdpackage \package]; indicates documentation for a Java package (but also used with Python).
* <code>\package <name></code>, vedere [http://www.doxygen.nl/manual/commands.html#cmdpackage \package]; indica la documentazione per un pacchetto Java (ma è utilizzato anche con Python).
* <code>\fn (function declaration)</code>, see [http://www.doxygen.nl/manual/commands.html#cmdfn \fn]; documents a function.
* <code>\fn (function declaration)</code>, vedere [http://www.doxygen.nl/manual/commands.html#cmdfn \fn]; documenta una funzione.
* <code>\var (variable declaration)</code>, see [http://www.doxygen.nl/manual/commands.html#cmdvar \var]; documents a variable; it is equivalent to {{incode|\fn}}, {{incode|\property}}, and {{incode|\typedef}}.
* <code>\var (variable declaration)</code>, vedere [http://www.doxygen.nl/manual/commands.html#cmdvar \var]; documenta una variabile; è equivalente a {{incode|\fn}}, {{incode|\property}}, e {{incode|\typedef}}.
* <code>\section <section-name> (section title)</code>, see [http://www.doxygen.nl/manual/commands.html#cmdsection \section]; starts a section.
* <code>\section <section-name> (section title)</code>, vedere [http://www.doxygen.nl/manual/commands.html#cmdsection \section]; inizia una sessione.
* <code>\subsection <subsection-name> (subsection title)</code>, see [http://www.doxygen.nl/manual/commands.html#cmdsubsection \subsection]; starts a subsection.
* <code>\subsection <subsection-name> (subsection title)</code>, vedere [http://www.doxygen.nl/manual/commands.html#cmdsubsection \subsection]; inizia una sottosessione.
* <code>\namespace <name></code>, see [http://www.doxygen.nl/manual/commands.html#cmdnamespace \namespace]; indicates information for a namespace.
* <code>\namespace <name></code>, vedere [http://www.doxygen.nl/manual/commands.html#cmdnamespace \namespace]; indica le informazioni per uno spazio dei nomi.
* <code>\cond [(section-label)]</code>, and <code>\endcond</code>, see [http://www.doxygen.nl/manual/commands.html#cmdcond \cond]; defines a block to conditionally document or omit.
* <code>\cond [(section-label)]</code>, e <code>\endcond</code>, vedere [http://www.doxygen.nl/manual/commands.html#cmdcond \cond]; definisce un blocco da documentare o omettere in modo condizionale.
* <code>\a <word></code>, see [http://www.doxygen.nl/manual/commands.html#cmda \a]; displays the argument in italics for emphasis.
* <code>\a <word></code>, vedere [http://www.doxygen.nl/manual/commands.html#cmda \a]; visualizza l'argomento in corsivo per dare enfasi.
* <code>\param [(dir)] <parameter-name> { parameter description }</code>, see [http://www.doxygen.nl/manual/commands.html#cmdparam \param]; indicates the parameter of a function.
* <code>\param [(dir)] <parameter-name> { parameter description }</code>, vedere [http://www.doxygen.nl/manual/commands.html#cmdparam \param]; indica il parametro di una funzione.
* <code>\return { description of the return value }</code>, see [http://www.doxygen.nl/manual/commands.html#cmdreturn \return]; specifies the return value.
* <code>\return { description of the return value }</code>, vedere [http://www.doxygen.nl/manual/commands.html#cmdreturn \return]; specifica il valore restituito.
* <code>\sa { references }</code>, see [http://www.doxygen.nl/manual/commands.html#cmdsa \sa]; prints "See also".
* <code>\sa { references }</code>, vedere [http://www.doxygen.nl/manual/commands.html#cmdsa \sa]; stampa "See also".
* <code>\note { text }</code>, see [http://www.doxygen.nl/manual/commands.html#cmdnote \note]; adds a paragraph to be used as a note.
* <code>\note { text }</code>, vedere [http://www.doxygen.nl/manual/commands.html#cmdnote \note]; aggiunge un paragrafo da utilizzare come nota.
</div>
</div>
</div>
</div>


<span id="Markdown_support"></span>
== Markdown support ==
== Supporto al Markdown ==


Since Doxygen 1.8, Markdown syntax is recognized in documentation blocks. Markdown is a minimalistic formatting language inspired by plain text email which, similar to wiki syntax, intends to be simple and readable without requiring complicated code like that found in HTML, LaTeX or Doxygen's own commands. Markdown has gained popularity with free software, especially in online platforms like Github, as it allows creating documentation without using complicated code. See the [http://www.doxygen.nl/manual/markdown.html Markdown support] section in the Doxygen manual to learn more. Visit the [https://daringfireball.net/projects/markdown/ Markdown website] to learn more about the origin and philosophy of Markdown.
A partire da Doxygen 1.8, la sintassi Markdown è riconosciuta dai blocchi di documentazione. Markdown è un linguaggio di formattazione minimalista ispirato all'e-mail di testo semplice che, simile alla sintassi wiki, intende essere semplice e leggibile senza richiedere codice complicato come quello che si trova in HTML, LaTeX o i comandi di Doxygen. Markdown ha guadagnato popolarità con il software libero, specialmente nelle piattaforme online come Github, in quanto consente di creare documentazione senza utilizzare codice complicato. Consultare la sezione [http://www.doxygen.nl/manual/markdown.html Markdown support] nel manuale Doxygen per saperne di più. Visitare il [https://daringfireball.net/projects/markdown/ sito web di Markdown] per saperne di più sull'origine e la filosofia di Markdown.


Doxygen supports a standard set of Markdown instructions, as well as some extensions such as [https://github.github.com/github-flavored-markdown/ Github Markdown].
Doxygen supporta un set standard di istruzioni Markdown, nonché alcune estensioni come [https://github.github.com/github-flavored-markdown/ Github Markdown].
<div class="mw-collapsible mw-collapsed toccolours">
<div class="mw-collapsible mw-collapsed toccolours">
Di seguito vengono presentati alcuni esempi di formattazione Markdown.
Some examples of Markdown formatting are presented next.


<div class="mw-collapsible-content">
<div class="mw-collapsible-content">
The following is standard Markdown.
Quello che segue è Markdown standard.
{{Code|code=
{{Code|code=
Ecco il testo per un paragrafo.
Here is text for one paragraph.


Continuiamo con altro testo in un altro paragrafo.
We continue with more text in another paragraph.


Questa è un'intestazione di livello 1
This is a level 1 header
========================
========================


Questa è un'intestazione di livello 2
This is a level 2 header
------------------------
------------------------


# Questa è un'intestazione di livello 1
# This is a level 1 header


### This is level 3 header #######
### Questa è l'intestazione di livello 3 #######


> Questa è un blocco di citazione
> This is a block quote
> su più righe
> spanning multiple lines


- Item 1
- Articolo 1


More text for this item.
Altro testo per questo articolo.


- Item 2
- Punto 2
* nested list item.
* voce di elenco nidificata.
* un altro elemento nidificato.
* another nested item.
- Item 3
- Punto 3


1. First item.
1. Primo elemento.
2. Second item.
2. Secondo elemento.


*asterisco singolo: enfasi*
*single asterisks: emphasis*


_sottolineature singole_
_single underscores_


**double asterisks: strong emphasis**
**doppio asterisco: enfasi forte**


__sottolineature doppie__
__double underscores__


Questo è un paragrafo normale
This a normal paragraph


This is a code block
Questo è un blocco di codice


Continuiamo di nuovo con un paragrafo normale.
We continue with a normal paragraph again.


Use the `printf()` function. Inline `code`.
Usa la funzione `printf()`. `codice` inline.


[The link text](http://example.net/)
[Il testo del link](http://example.net/)


![Caption text](/path/to/img.jpg)
![Testo della didascalia](/path/to/img.jpg)


<http://www.example.com>
<http://www.example.com>
}}
}}


Le seguenti sono estensioni di Markdown.
The following are Markdown extensions.
<pre>
<pre>
[TOC]
[TOC]


Prima intestazione | Seconda intestazione
First Header | Second Header
------------- | -------------
----------------------| ---------------------
Contenuto della Cella | Contenuto della Cella
Content Cell | Content Cell
Contenuto della Cella | Contenuto della Cella
Content Cell | Content Cell


<nowiki>~~~~~~~~~~~~~</nowiki>{.py}
<nowiki>~~~~~~~~~~~~~</nowiki>{.py}
Line 365: Line 379:
</div>
</div>


<span id="Parsing_of_documentation_blocks"></span>
== Parsing of documentation blocks ==
== Analisi dei blocchi della documentazione ==


Il testo all'interno di uno speciale blocco di documentazione viene analizzato prima di essere scritto nei file di output HTML e LaTeX. Durante l'analisi si verificano i seguenti passaggi:
The text inside a special documentation block is parsed before it is written to the HTML and LaTeX output files. During parsing the following steps take place:
* La formattazione Markdown è sostituita dall'HTML corrispondente o da comandi speciali.
* Markdown formatting is replaced by corresponding HTML or special commands.
* The special commands inside the documentation are executed. See the section [http://www.doxygen.nl/manual/commands.html Special Commands] in the manual for an explanation of each command.
* Vengono eseguiti i comandi speciali all'interno della documentazione. Vedere la sezione [http://www.doxygen.nl/manual/commands.html Comandi speciali] nel manuale per una spiegazione di ciascun comando.
* Se una riga inizia con degli spazi bianchi seguiti da uno o più asterischi ({{incode|*}}) e poi facoltativamente altri spazi bianchi, tutti gli spazi bianchi e gli asterischi vengono rimossi.
* If a line starts with some whitespace followed by one or more asterisks ({{incode|*}}) and then optionally more whitespace, then all whitespace and asterisks are removed.
* Tutte le righe vuote risultanti vengono trattate come separatori di paragrafo.
* All resulting blank lines are treated as paragraph separators.
* I collegamenti vengono creati automaticamente per le parole corrispondenti a classi o funzioni documentate. Se la parola è preceduta da un simbolo di percentuale {{incode|%}}, questo simbolo viene rimosso e non viene creato alcun collegamento per la parola.
* Links are automatically created for words corresponding to documented classes or functions. If the word is preceded by a percentage symbol {{incode|%}}, then this symbol is removed, and no link is created for the word.
* Links are created when certain patterns are found in the text. See the section [http://www.doxygen.nl/manual/autolink.html Automatic link generation] in the manual for more information.
* I collegamenti vengono creati quando nel testo vengono trovati determinati schemi. Vedere la sezione [http://www.doxygen.nl/manual/autolink.html Generazione automatica di link] nel manuale per ulteriori informazioni.
* HTML tags that are in the documentation are interpreted and converted to LaTeX equivalents for the LaTeX output. See the section [http://www.doxygen.nl/manual/htmlcmds.html HTML Commands] in the manual for an explanation of each supported HTML tag.
* I tag HTML presenti nella documentazione vengono interpretati e convertiti in equivalenti LaTeX per l'output LaTeX. Vedere la sezione [http://www.doxygen.nl/manual/htmlcmds.html Comandi HTML] nel manuale per una spiegazione di ciascun tag HTML supportato.


<span id="Doxygen_with_Python_code"></span>
== Doxygen with Python code ==
== Doxygen con codice Python ==


Doxygen works best for statically typed languages like C++. However, it can also create [http://www.doxygen.nl/manual/docblocks.html#pythonblocks documentation for Python files].
Doxygen funziona meglio per linguaggi tipizzati staticamente come C++. Tuttavia, può anche creare [http://www.doxygen.nl/manual/docblocks.html#pythonblocks documentazione per i file Python].


Esistono due modi per scrivere blocchi di documentazione per Python:
There are two ways to write documentation blocks for Python:
# The Pythonic way, using "docstrings", that is, a block of text surrounded by <code><nowiki>'''triple quotes'''</nowiki></code> immediately after the class or function definition.
# Il modo Pythonico, usando "docstrings", cioè un blocco di testo racchiuso tra <code><nowiki>'''virgolette triple'''</nowiki></code> subito dopo la definizione della classe o della funzione.
# Il modo Doxygen, inserendo i commenti prima della definizione della classe o della funzione; in questo caso vengono utilizzati i doppi caratteri hash {{incode|##}} per iniziare il blocco di documentazione, e quindi un singolo carattere hash può essere utilizzato nelle righe successive.
# The Doxygen way, putting comments before the class or function definition; in this case double hash characters {{incode|##}} are used to start the documentation block, and then a single hash character can be used in subsequent lines.


Nota:
Note:
* The first option is preferred to comply with [https://www.python.org/dev/peps/pep-0008/#documentation-strings PEP8], [https://www.python.org/dev/peps/pep-0257/ PEP257] and most style guidelines for writing Python (see [https://realpython.com/python-pep8/ 1], [https://realpython.com/documenting-python-code/ 2]). It is recommended to use this style if you intend to produce documented sources using [https://www.sphinx-doc.org/en/master/ Sphinx], which is a very common tool to document Python code. If you use this style, Doxygen will be able to extract the comments verbatim, but Doxygen special commands starting with {{incode|\}} or {{incode|@}} won't work.
* La prima opzione è preferita per rispettare [https://www.python.org/dev/peps/pep-0008/#documentation-strings PEP8], [https://www.python.org/dev/peps/ pep-0257/ PEP257] e la maggior parte delle linee guida di stile per la scrittura di Python (vedere [https://realpython.com/python-pep8/ 1], [https://realpython.com/documenting-python-code/ 2]). Si consiglia di utilizzare questo stile se si intende produrre fonti documentate utilizzando [https://www.sphinx-doc.org/en/master/ Sphinx], che è uno strumento molto comune per documentare il codice Python. Se usi questo stile, Doxygen sarà in grado di estrarre i commenti alla lettera, ma i comandi speciali di Doxygen che iniziano con {{incode|\}} o {{incode|@}} non funzioneranno.
* The second option isn't the traditional Python style, but it allows you to use Doxygen's special commands like {{incode|\param}} and {{incode|\var}}.
* La seconda opzione non è il tradizionale stile Python, ma ti permette di usare i comandi speciali di Doxygen come {{incode|\param}} e {{incode|\var}}.


<span id="First_style:_Pythonic_documentation"></span>
=== First style: Pythonic documentation ===
=== Primo stile: documentazione Pythonica ===


Nell'esempio seguente una docstring è all'inizio per spiegare i contenuti generali di questo modulo (file). Quindi le docstring appaiono all'interno delle definizioni di funzione, classe e metodo di classe. In questo modo Doxygen estrarrà i commenti e li presenterà così come sono, senza modifiche.
In the following example one docstring is at the beginning to explain the general contents of this module (file). Then docstrings appear inside the function, class, and class method definitions. In this way, Doxygen will extract the comments and present them as is, without modification.


{{Code|code=
{{Code|code=
'''@package pyexample_a
'''@package pyexample_a
Documentazione per questo modulo.
Documentation for this module.
Maggiori dettagli.
More details.
'''
'''




def func():
def func():
'''Documentation for a function.
'''Documentazione per una funzione.
More details.
Maggiori dettagli.
'''
'''
pass
pass
Line 407: Line 424:


class PyClass:
class PyClass:
'''Documentation for a class.
'''Documentazione per una classe.
More details.
Maggiori dettagli.
'''
'''


def __init__(self):
def __init__(self):
'''The constructor.'''
'''Il costruttore.'''
self._memVar = 0
self._memVar = 0


def PyMethod(self):
def PyMethod(self):
'''Documentation for a method.'''
'''Documentazione per un metodo.'''
pass
pass
}}
}}


<span id="Second_style:_documentation_block_before_the_code"></span>
=== Second style: documentation block before the code ===
=== Secondo stile: blocco di documentazione prima del codice ===


In the following example the documentation blocks start with double hash signs {{incode|##}}. One appears at the beginning to explain the general content of this module (file). Then there are blocks before the function, class, and class method definitions, and there is one block after a class variable. In this way, Doxygen will extract the documentation, recognize the special commands {{incode|@package}}, {{incode|@param}}, and {{incode|@var}}, and format the text accordingly.
Nell'esempio seguente i blocchi di documentazione iniziano con doppi cancelletti {{incode|##}}. Uno appare all'inizio per spiegare il contenuto generale di questo modulo (file). Quindi ci sono blocchi prima delle definizioni di funzione, classe e metodo di classe e c'è un blocco dopo una variabile di classe. In questo modo, Doxygen estrarrà la documentazione, riconoscerà i comandi speciali {{incode|@package}}, {{incode|@param}} e {{incode|@var}} e formatterà il testo di conseguenza.
{{Code|code=
{{Code|code=
## @package pyexample_b
## @package pyexample_b
Line 457: Line 475:
}}
}}


<span id="Compiling_the_documentation"></span>
=== Compiling the documentation ===
=== Compilazione della documentazione ===


Compilation of documentation proceeds the same as [[#Compiling the documentation|for C++ sources]]. If both Python files, {{incode|pyexample_a.py}} and {{incode|pyexample_b.py}}, with distinct commenting style are in the same directory, both will be processed.
La compilazione della documentazione procede come [[#Compilazione della documentazione|per i sorgenti C++]]. Se entrambi i file Python, {{incode|pyexample_a.py}} e {{incode|pyexample_b.py}}, con uno stile di commento distinto si trovano nella stessa directory, verranno elaborati entrambi.
{{Code|code=
{{Code|code=
cd toplevel-source/
cd toplevel-source/
Line 467: Line 486:
}}
}}


La documentazione dovrebbe mostrare informazioni simili alle seguenti e creare collegamenti appropriati ai singoli moduli e classi.
The documentation should show similar information to the following, and create appropriate links to the individual modules and classes.
{{Code|code=
{{Code|code=
Class List
Class List
Line 479: Line 498:
}}
}}


<span id="Converting_the_Pythonic_style_to_Doxygen_style"></span>
=== Converting the Pythonic style to Doxygen style ===
=== Conversione dello stile Pythonico in stile Doxygen ===


In the previous example, the Python file that is commented in a [[#Second style: documentation block before the code|Doxygen style]] shows more detailed information and formatting for its classes, functions, and variables. The reason is that this style allows Doxygen to extract the special commands that start with {{incode|\}} or {{incode|@}}, while the [[#First style: Pythonic documentation|Pythonic style]] does not. Therefore, it would be desirable to convert the Pythonic style to Doxygen style before compiling the documentation. This is possible with an auxiliary Python program called [https://github.com/Feneric/doxypypy doxypypy]. This program is inspired by an older program called [https://github.com/Feneric/doxypy doxypy], which would take the Pythonic <code><nowiki>'''docstrings'''</nowiki></code> and convert them to the Doxygen comment blocks that start with a double hash {{incode|##}}. Doxypypy goes further than this, as it analyzes the docstrings and extracts items of interest like variables and arguments, and even doctests (example code in the docstrings).
Nell'esempio precedente, il file Python commentato in un [[#Secondo stile: blocco della documentazione altrove|stile Doxygen]] mostra informazioni e formattazione più dettagliate per le sue classi, funzioni e variabili. Il motivo è che questo stile consente a Doxygen di estrarre i comandi speciali che iniziano con {{incode|\}} o {{incode|@}}, mentre lo [[#Primo stile: blocco della documentazione prima del codice|stle Pythonico]] no. Pertanto, sarebbe desiderabile convertire lo stile Pythonico in stile Doxygen prima di compilare la documentazione. Questo è possibile con un programma Python ausiliario chiamato [https://github.com/Feneric/doxypypy doxypypy]. Questo programma è ispirato a un vecchio programma chiamato [https://github.com/Feneric/doxypy doxypy], che prende le <code><nowiki>'''docstrings''' di Python</nowiki></code> e le converte nei blocchi di commenti Doxygen che iniziano con un doppio hash {{incode|##}}. Doxypypy va oltre, poiché analizza le docstring ed estrae elementi di interesse come variabili e argomenti e persino doctest (codice di esempio nelle docstring).


Doxypypy can be installed using {{incode|pip}}, the Python package installer.
Doxypypy può essere installato usando {{incode|pip}}, il programma di installazione dei pacchetti Python.
{{Code|code=
{{Code|code=
pip3 install --user doxypypy
pip3 install --user doxypypy
}}
}}


If the {{incode|pip}} command is used without the {{incode|--user}} option, it will require superuser (root) privileges to install the package, but this is not needed in most cases; use root permissions only if you are certain the package won't collide with your distribution provided packages.
Se il comando {{incode|pip}} viene utilizzato senza l'opzione {{incode|--user}}, saranno necessari i privilegi di superutente (root) per installare il pacchetto, ma ciò non è necessario nella maggior parte dei casi; usare i permessi di root solo se sei certo che il pacchetto non entrerà in collisione con i pacchetti forniti dalla tua distribuzione.


If the package was installed as a user, it may reside in your home directory, for example, in {{incode|$HOME/.local/bin}}. If this directory is not in your system's {{incode|PATH}}, the program will not be found. Therefore, add the directory to the {{incode|PATH}} variable, either in your {{incode|$HOME/.bashrc}} file, or in your {{incode|$HOME/.profile}} file.
Se il pacchetto è stato installato come utente, potrebbe risiedere nella tua home directory, ad esempio in {{incode|$HOME/.local/bin}}. Se questa directory non è nel {{incode|PATH}} del tuo sistema, il programma non verrà trovato. Pertanto, aggiungere la directory alla variabile {{incode|PATH}}, nel file {{incode|$HOME/.bashrc}} o nel file {{incode|$HOME/.profile}}.
{{Code|code=
{{Code|code=
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/.local/bin:$PATH"
}}
}}


Alternatively, you can create a symbolic link to the {{incode|doxypypy}} program, placing the link in a directory that is already included in the {{incode|PATH}}.
In alternativa, si può creare un collegamento simbolico al programma {{incode|doxypypy}}, posizionando il collegamento in una directory che è già inclusa nel {{incode|PATH}}.
{{Code|code=
{{Code|code=
mkdir -p $HOME/bin
mkdir -p $HOME/bin
Line 501: Line 521:
}}
}}


Once the {{incode|doxypypy}} program is installed, and accessible from the terminal, a Python file with Pythonic docstrings can be reformatted to Doxygen style with the following instructions. The program outputs the reformatted code to standard output, so redirect this output to a new file.
Una volta che il programma {{incode|doxypypy}} è installato e accessibile dal terminale, un file Python con docstring Pythonic può essere riformattato in stile Doxygen con le seguenti istruzioni. Il programma invia il codice riformattato allo standard output, quindi reindirizza questo output a un nuovo file.
{{Code|code=
{{Code|code=
doxypypy -a -c pyexample_pythonic.py > pyexample_doxygen.py
doxypypy -a -c pyexample_pythonic.py > pyexample_doxygen.py
Line 626: Line 646:
</div>
</div>


The original file has a comment at the top <code><nowiki>'''@package pyexample_pythonic</nowiki></code> that indicates the module or namespace that is being described by the file. This {{incode|@package}} keyword is not interpreted when using triple quotes in the comment block.
Il file originale ha un commento in alto <code><nowiki>'''@package pyexample_pythonic</nowiki></code> che indica il modulo o lo spazio dei nomi che viene descritto dal file. Questa parola chiave {{incode|@package}} non viene interpretata quando si utilizzano le virgolette triple nel blocco dei commenti.


In the new file the commenting style is changed so the line becomes {{incode|##@package pyexample_pythonic}}, which now will be interpreted by Doxygen. However, to be interpreted correctly, the argument has to be edited manually to match the new module (file) name; after doing this the line should be {{incode|##@package pyexample_doxygen}}.
Nel nuovo file lo stile di commento è cambiato in modo che la riga diventi {{incode|##@package pyexample_pythonic}}, che ora sarà interpretata da Doxygen. Tuttavia, per essere interpretato correttamente, l'argomento deve essere modificato manualmente in modo che corrisponda al nome del nuovo modulo (file); dopo aver fatto questo la riga dovrebbe essere {{incode|##@package pyexample_doxygen}}.


<div class="mw-collapsible mw-collapsed toccolours">
div class="mw-collapsible mw-collapsed toccolours">
{{incode|pyexample_doxygen.py}} (the top is manually edited, the rest stays the same)
{{incode|pyexample_doxygen.py}} (la parte superiore viene modificata manualmente, il resto rimane invariato)


<div class="mw-collapsible-content">
<div class="mw-collapsible-content">
Line 643: Line 663:
</div>
</div>


To compile, create the configuration, and run {{incode|doxygen}} in the toplevel directory that contains the files.
Per compilare, creare la configurazione ed eseguire {{incode|doxygen}} nella directory di livello superiore che contiene i file.
{{Code|code=
{{Code|code=
cd toplevel-source/
cd toplevel-source/
Line 651: Line 671:
}}
}}


La documentazione dovrebbe mostrare informazioni simili alle seguenti e creare collegamenti appropriati ai singoli moduli.
The documentation should show similar information to the following, and create appropriate links to the individual modules.
{{Code|code=
{{Code|code=
Namespace List
Namespace List
Line 660: Line 680:
}}
}}


<span id="Converting_the_comment_style_on_the_fly"></span>
=== Converting the comment style on the fly ===
=== Conversione immediata dello stile del commento ===


Nell'esempio precedente, la conversione dei blocchi di documentazione è stata eseguita manualmente con un solo file sorgente. Idealmente si desidera che questa conversione avvenga automaticamente, al volo, con qualsiasi numero di file Python. Per fare ciò, la configurazione Doxygen deve essere modificata di conseguenza.
In the previous example, the conversion of the documentation blocks was done manually with only one source file. Ideally we want this conversion to occur automatically, on the fly, with any number of Python files. To do this, the Doxygen configuration must be edited accordingly.


To start, don't use the {{incode|doxypypy}} program directly; instead, create the configuration file with {{incode|doxygen -g}}, then edit the created {{incode|Doxyfile}}, and modify the following tag.
Per iniziare, non utilizzare direttamente il programma {{incode|doxypypy}}; invece, creare il file di configurazione con {{incode|doxygen -g}}, quindi modificare il {{incode|Doxyfile}} creato e modificare il seguente tag.
{{Code|code=
{{Code|code=
FILTER_PATTERNS = *.py=doxypypy_filter
FILTER_PATTERNS = *.py=doxypypy_filter
}}
}}


What this does is that files that match the pattern, all files with a extension ending in {{incode|.py}}, will go through the {{incode|doxypypy_filter}} program. Every time Doxygen encounters such file in the source tree, the file name will be passed as the first argument to this program.
Quello che fa è che i file che corrispondono al modello, tutti i file con un'estensione che termina con {{incode|.py}}, passeranno attraverso il programma {{incode|doxypypy_filter}}. Ogni volta che Doxygen incontra tale file nell'albero dei sorgenti, il nome del file verrà passato come primo argomento a questo programma.
{{Code|code=
{{Code|code=
doxypypy_filter example.py
doxypypy_filter example.py
}}
}}


The {{incode|doxypypy_filter}} program does not exist by default; it should be created as a shell script to run {{incode|doxypypy}} with the appropriate options, and to take a file as its first argument.
Il programma {{incode|doxypypy_filter}} non esiste di default; dovrebbe essere creato come uno script di shell per eseguire {{incode|doxypypy}} con le opzioni appropriate e per prendere un file come primo argomento.
{{Code|code=
{{Code|code=
#!/bin/sh
#!/bin/sh
Line 680: Line 701:
}}
}}


After saving this shell script, make sure it has execute permissions, and that it is located in a directory contained in your system's {{incode|PATH}}.
Dopo aver salvato questo script di shell, assicurarsi che abbia i permessi di esecuzione e che si trovi in una directory contenuta nel {{incode|PATH}} del tuo sistema.
{{Code|code=
{{Code|code=
chmod a+x doxypypy_filter
chmod a+x doxypypy_filter
Line 686: Line 707:
}}
}}


On Windows systems, a batch file can be used in a similar way.
Sui sistemi Windows, un file batch può essere utilizzato in modo simile.
{{Code|code=
{{Code|code=
doxypypy -a -c %1
doxypypy -a -c %1
}}
}}


With this configuration done, the {{incode|doxygen Doxyfile}} command can be run to generate the documentation as usual. Every Python file using Pythonic <code><nowiki>'''triple quotes'''</nowiki></code> will be reformatted on the fly to use {{incode|##Doxygen}} style comments, and then will be processed by Doxygen, which now will be able to interpret the [[#Doxygen markup|special commands]] and [[#Markdown support|Mardown syntax]]. The original source code won't be modified, and no temporary file with a different name needs to be created as in [[#Converting the Pythonic style to Doxygen style|the previous section]]; therefore, if a {{incode|@package example}} instruction is found, it doesn't need to be changed manually.
Con questa configurazione impostata, il comando {{incode|doxygen Doxyfile}} può essere eseguito per generare la documentazione come di consueto. Per ogni file Python che usa <code><nowiki>'''virgolette triple'''</nowiki></code> Pythonic sarà riformattato al volo per usare i commenti in stile {{incode|##Doxygen}}, e poi questi saranno elaborati da Doxygen, che quindi sarà in grado di interpretare i [[#markup di Doxygen|comandi speciali]] e la [[#Supporto al Markdown|sintassi markdown]]. Il codice sorgente originale non verrà modificato e non è necessario creare alcun file temporaneo con un nome diverso come [[#Conversione dello stile Pythonico in stile Doxygen|nella sezione precedente]]; pertanto, se viene trovata un'istruzione {{incode|@package example}}, non è necessario modificarla manualmente.


Note that existing Python files which already use the {{incode|##double hash}} style for their comment blocks won't be affected by the {{incode|doxypypy}} filter, and will be processed by Doxygen normally.
Nota che i file Python esistenti che usano già lo stile {{incode|##doppio cancelletto}} per i loro blocchi di commenti non saranno influenzati dal filtro {{incode|doxypypy}} e saranno processati normalmente da Doxygen.


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


{{Caption|General workflow to produce source code documentation with Doxygen, when the Python files are filtered to transform the comment blocks.}}
{{Caption|Flusso di lavoro generale per produrre la documentazione del codice sorgente con Doxygen, quando i file Python vengono filtrati per trasformare i blocchi dei commenti.}}


<span id="Python_code_quality_check"></span>
=== Python code quality check ===
=== Controllo della qualità del codice Python ===


To use the automatic conversion of documentation blocks it is important that the original Python sources are correctly written, following the Pythonic guidelines in [https://www.python.org/dev/peps/pep-0008/#documentation-strings PEP8] and [https://www.python.org/dev/peps/pep-0257/ PEP257]. Sloppily written code will cause {{incode|doxypypy}} to fail when processing the file, and thus Doxygen will be unable to format the documentation correctly.
Per utilizzare la conversione automatica dei blocchi di documentazione è importante che i sorgenti Python originali siano scritti correttamente, seguendo le linee guida Pythonic in [https://www.python.org/dev/peps/pep-0008/#documentation-strings PEP8] e [https://www.python.org/dev/peps/pep-0257/ PEP257]. Un codice scritto in modo approssimativo causerà il fallimento di {{incode|doxypypy}} durante l'elaborazione del file, e quindi Doxygen non sarà in grado di formattare correttamente la documentazione.


<div class="mw-collapsible mw-collapsed toccolours">
<div class="mw-collapsible mw-collapsed toccolours">
The following commenting styles will not allow parsing of the docstrings by {{incode|doxypypy}}, so they should be avoided.
I seguenti stili di commento non consentiranno l'analisi delle docstring da parte di {{incode|doxypypy}}, quindi dovrebbero essere evitati.


<div class="mw-collapsible-content">
<div class="mw-collapsible-content">
Line 740: Line 762:
</div>
</div>


Usa sempre le virgolette triple per le docstring e assicurati che seguano immediatamente la dichiarazione della classe o della funzione.
Always use triple quotes for the docstrings, and make sure they immediately follow the class or function declaration.


It is also a good idea to verify the quality of your Python code with a tool such as [http://flake8.pycqa.org/en/latest/ flake8] ([https://gitlab.com/pycqa/flake8 Gitlab]). Flake8 primarily combines three tools, [https://github.com/PyCQA/pyflakes Pyflakes], [https://github.com/PyCQA/pycodestyle Pycodestyle] (formerly pep8), and the [https://github.com/PyCQA/mccabe McCabe complexity checker], in order to enforce proper Pythonic style.
È anche una buona idea verificare la qualità del tuo codice Python con uno strumento come [http://flake8.pycqa.org/en/latest/ flake8] ([https://gitlab.com/pycqa/flake8 Gitlab ]). Flake8 combina principalmente tre strumenti, [https://github.com/PyCQA/pyflakes Pyflakes], [https://github.com/PyCQA/pycodestyle Pycodestyle] (precedentemente pep8) e [https://github.com /PyCQA/mccabe Controllo della complessità di McCabe], al fine di applicare il corretto stile Pythonic.


{{Code|code=
{{Code|code=
Line 749: Line 771:
}}
}}


To check all files inside a source tree use {{incode|find}}.
Per controllare tutti i file all'interno di un albero dei sorgenti usa {{incode|find}}.
{{Code|code=
{{Code|code=
find toplevel-source/ -name '*.py' -exec flake8 {} '+'
find toplevel-source/ -name '*.py' -exec flake8 {} '+'
}}
}}


If the project demands it, some code checks deemed too strict can be ignored. The error codes can be consulted in the [https://pycodestyle.readthedocs.io/en/latest/intro.html#error-codes Pycodestyle documentation].
Se il progetto lo richiede, alcuni controlli del codice ritenuti troppo severi possono essere ignorati. I codici di errore possono essere consultati nella [https://pycodestyle.readthedocs.io/en/latest/intro.html#error-codes Documentazione di Pycodestyle].
{{Code|code=
{{Code|code=
find toplevel-source/ -name '*.py' -exec flake8 --ignore=E266,E402,E722,W503 --max-line-length=100 {} '+'
find toplevel-source/ -name '*.py' -exec flake8 --ignore=E266,E402,E722,W503 --max-line-length=100 {} '+'
}}
}}


In similar way, a program that primarily checks that comments comply with [https://www.python.org/dev/peps/pep-0257/ PEP257] is [https://github.com/PyCQA/pydocstyle Pydocstyle]. The error codes can be consulted in the [http://www.pydocstyle.org/en/4.0.0/error_codes.html Pydocstyle documentation].
In modo simile, un programma che controlla principalmente che i commenti siano conformi a [https://www.python.org/dev/peps/pep-0257/ PEP257] è [https://github.com/PyCQA/pydocstyle Pydocstyle]. I codici di errore possono essere consultati nella [http://www.pydocstyle.org/en/4.0.0/error_codes.html documentazione di Pydocstyle].
{{Code|code=
{{Code|code=
pip install --user pydocstyle
pip install --user pydocstyle
Line 765: Line 787:
}}
}}


Also use it with {{incode|find}} to perform docstring checks on all source files.
Usalo anche con {{incode|find}} per eseguire controlli docstring su tutti i file sorgente.
{{Code|code=
{{Code|code=
find toplevel-source/ -name '*.py' -exec pydocstyle {} '+'
find toplevel-source/ -name '*.py' -exec pydocstyle {} '+'
}}
}}


<span id="Source_documentation_with_Sphinx"></span>
== Source documentation with Sphinx ==
== Documentazione del sorgente con Sphinx ==

[https://www.sphinx-doc.org/en/master/ Sphinx] è il sistema più popolare per documentare il codice sorgente Python. Tuttavia, poiché le funzioni principali e gli ambienti di lavoro di FreeCAD sono scritti in C++, si è ritenuto che Doxygen fosse uno strumento di documentazione migliore per questo progetto.

Mentre Sphinx può analizzare in modo nativo le docstring Python, analizzare i sorgenti C++ richiede un po' più di lavoro. Il progetto [https://breathe.readthedocs.io/en/latest/ Breathe] ([https://github.com/michaeljones/breathe Github]) è un tentativo di colmare il divario tra Sphinx e Doxygen, al fine di integrare la documentazione del codice sorgente sia Python che C++ nello stesso sistema. Innanzitutto, Doxygen deve essere configurato per produrre un file XML; l'output XML viene quindi letto da Breathe e convertito in input adatto per Sphinx.


Consultare la [https://breathe.readthedocs.io/en/latest/quickstart.html Guida rapida] della documentazione di Breathe per saperne di più su questo processo.
[https://www.sphinx-doc.org/en/master/ Sphinx] is the most popular system to document Python source code. However, since FreeCAD's core functions and workbenches are written in C++ it was deemed that Doxygen is a better documentation tool for this project.


Vedi questa risposta in [https://stackoverflow.com/a/35377654 Stackoverflow] per altre alternative alla documentazione del codice C++ e Python insieme nello stesso progetto.
While Sphinx can natively parse Python docstrings, it requires a bit more work to parse C++ sources. The [https://breathe.readthedocs.io/en/latest/ Breathe] ([https://github.com/michaeljones/breathe Github]) project is an attempt at bridging the gap between Sphinx and Doxygen, in order to integrate both Python and C++ source code documentation in the same system. First, Doxygen needs to be configured to output an XML file; the XML output is then read by Breathe, and converted to suitable input for Sphinx.


<span id="Related"></span>
See the [https://breathe.readthedocs.io/en/latest/quickstart.html Quick start guide] in the Breathe documentation to know more about this process.
== Relazioni ==


* [[Source_documentation/it|Documentazione del sorgente]]
See this answer in [https://stackoverflow.com/a/35377654 Stackoverflow] for other alternatives to documenting C++ and Python code together in the same project.
* [https://www.freecadweb.org/api/ Sito web della API di FreeCAD]


[[Category:Developer_Documentation]]
[[Category:Developer_Documentation{{#translation:}}]]
[[Category:Developer{{#translation:}}]]
[[Category:3rd Party{{#translation:}}]]

Latest revision as of 12:27, 11 August 2023

Other languages:

Introduzione

Doxygen è uno strumento popolare per la generazione di documentazione da sorgenti C++ annotate; supporta anche altri linguaggi di programmazione popolari come C#, PHP, Java e Python. Visitare il sito web Doxygen per saperne di più sul sistema e consultare il Manuale Doxygen per informazioni complete.

Doxygen e FreeCAD

Questo documento fornisce una breve introduzione a Doxygen, in particolare a come viene utilizzato in FreeCAD per documentarne i sorgenti. Visitare la pagina documentazione del codice sorgente per istruzioni sulla creazione della documentazione di FreeCAD, anch'essa ospitata online sul sito web dell'API di FreeCAD.

Flusso di lavoro generale per produrre documentazione del codice sorgente con Doxygen.

Doxygen col codice C++

La sezione Getting started (Step 3) del manuale Doxygen menziona i modi di base per documentare le fonti.

Per i membri, le classi e gli spazi dei nomi ci sono fondamentalmente due opzioni:

  1. Posizionare uno speciale "blocco di documentazione" (un paragrafo commentato) prima della dichiarazione o della definizione della funzione, membro, classe o spazio dei nomi. Per i membri di file, delle classi e dello spazio dei nomi (variabili) è anche consentito posizionare la documentazione direttamente dopo il membro. Vedere la sezione Blocchi di commenti speciali nel manuale per saperne di più su questi blocchi.
  2. Posizionare un blocco di documentazione speciale da qualche altra parte (un altro file o un'altra posizione nello stesso file) e inserire un "comando strutturale" nel blocco di documentazione. Un comando strutturale collega un blocco di documentazione a una determinata entità che può essere documentata (una funzione, un membro, una variabile, una classe, uno spazio dei nomi o un file). Vedere la sezione Documentazione in altri luoghi ​​nel manuale per saperne di più sui comandi strutturali.

Nota:

  • Il vantaggio della prima opzione è che non si deve ripetere il nome dell'entità (funzione, membro, variabile, classe o spazio dei nomi), poiché Doxygen analizzerà il codice ed estrarrà le informazioni rilevanti.
  • I file possono essere documentati solo utilizzando la seconda opzione, poiché non è possibile inserire un blocco di documentazione prima di un file. Naturalmente, i membri del file (funzioni, variabili, typedef, define) non necessitano di un comando strutturale esplicito; semplicemente mettendo un blocco di documentazione prima o dopo di questi tutto funzionerà correttamente.

Primo stile: blocco della documentazione prima del codice

Di solito si desidera documentare il codice nel file di intestazione, appena prima della dichiarazione di classe o del prototipo di funzione. Ciò mantiene la dichiarazione e la documentazione vicine l'una all'altra, quindi è facile aggiornare quest'ultima se la prima cambia.

Il blocco di documentazione speciale inizia come un commento in stile C /* ma ha un asterisco aggiuntivo, quindi /**; il blocco termina con un */ corrispondente. Un'alternativa è utilizzare i commenti in stile C++ // con una barra aggiuntiva, quindi ///. 

/**
 * 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);

Secondo stile: blocco della documentazione altrove

In alternativa, la documentazione può essere collocata in un altro file (o nello stesso file in alto o in basso, o dovunque), lontano dalla dichiarazione di classe o dal prototipo di funzione. In questo caso, avrai informazioni duplicate, una volta nel file di origine effettivo e una volta nel file di documentazione.

Primo file, source.h: 

std::string name() const;
void setName(const std::string&);

Secondo file, source.h.dox: 

/** \file source.h
 *  \brief The documentation of source.h
 *   
 *   The details of this file go here.
 */

/** \fn std::string name() const;
 *  \brief Returns the name of the workbench object.
 */
/** \fn void setName(const std::string&);
 *  \brief Set the name to the workbench object.
 */

In questo caso viene usato il comando strutturale \file per indicare quale file sorgente si sta documentando; un comando strutturale \fn indica che il seguente codice è una funzione, e il comando \brief è usato per dare una breve descrizione di questa funzione.

Questo modalità di documentare un file sorgente è utile se vuoi solo aggiungere documentazione al tuo progetto senza aggiungere codice reale. Quando si inserisce un blocco di commento in un file con una delle seguenti estensioni .dox, .txt o .doc, Doxygen analizzerà i commenti e creerà la documentazione appropriata, ma nasconderà questo file ausiliario dall'elenco dei file.

Il progetto FreeCAD contiene diversi file che terminano con .dox in molte cartelle per fornire una descrizione, o esempi, del codice presente. È importante che tali file siano correttamente categorizzati in un gruppo o in uno spazio dei nomi, per il quale Doxygen fornisce alcuni comandi ausiliari come \defgroup, \ingroup e \namespace .

Esempio src/Base/core-base.dox; questo file nell'albero dei sorgenti di FreeCAD fornisce una breve spiegazione dello spazio dei nomi Base. 

/** \defgroup BASE Base
 *  \ingroup CORE
    \brief Basic structures used by other FreeCAD components
    
    The Base module includes most of the basic functions of FreeCAD, such as:
    - Console services: printing different kinds of messages to the FreeCAD report view or the terminal
    - Python interpreter: handles the execution of Python code in FreeCAD
    - Parameter handling: Management, saving and restoring of user preferences settings
    - Units: Management and conversion of different units

*/

/*! \namespace Base
    \ingroup BASE
    \brief Basic structures used by other FreeCAD components

    The Base module includes most of the basic functions of FreeCAD, such as:
    - Console services: printing different kinds of messages to the FreeCAD report view or the terminal
    - Python interpreter: handles the execution of Python code in FreeCAD
    - Parameter handling: Management, saving and restoring of user preferences settings
    - Units: Management and conversion of different units
*/

Un altro esempio è il file src/Gui/Command.cpp. Prima dei dettagli di implementazione dei metodi Gui::Command, c'è un blocco di documentazione che spiega alcuni dettagli del framework di comando di FreeCAD. Ha vari comandi \section per strutturare la documentazione. Include anche codice di esempio racchiuso in una coppia di parole chiave \code e \endcode; quando il file viene elaborato da Doxygen, questo esempio di codice verrà appositamente formattato per distinguersi. La parola chiave \ref viene utilizzata in diversi punti per creare collegamenti a sezioni, sottosezioni, pagine o ancore denominate altrove nella documentazione. Allo stesso modo, i comandi \see o \sa stampano "Vedi anche" e forniscono un collegamento ad altre classi, funzioni, metodi, variabili, file o URL.

Esempio src/Gui/Command.cpp 

/** \defgroup commands Command Framework
    \ingroup GUI
    \brief Structure for registering commands to the FreeCAD system
 * \section Overview
 * In GUI applications many commands can be invoked via a menu item, a toolbar button or an accelerator key. The answer of Qt to master this
 * challenge is the class \a QAction. A QAction object can be added to a popup menu or a toolbar and keep the state of the menu item and
 * the toolbar button synchronized.
 *
 * For example, if the user clicks the menu item of a toggle action then the toolbar button gets also pressed
 * and vice versa. For more details refer to your Qt documentation.
 *
 * \section Drawbacks
 * Since QAction inherits QObject and emits the \a triggered() signal or \a toggled() signal for toggle actions it is very convenient to connect
 * these signals e.g. with slots of your MainWindow class. But this means that for every action an appropriate slot of MainWindow is necessary
 * and leads to an inflated MainWindow class. Furthermore, it's simply impossible to provide plugins that may also need special slots -- without
 * changing the MainWindow class.
 *
 * \section wayout Way out
 * To solve these problems we have introduced the command framework to decouple QAction and MainWindow. The base classes of the framework are
 * \a Gui::CommandBase and \a Gui::Action that represent the link between Qt's QAction world and the FreeCAD's command world. 
 *
 * The Action class holds a pointer to QAction and CommandBase and acts as a mediator and -- to save memory -- that gets created 
 * (@ref Gui::CommandBase::createAction()) not before it is added (@ref Gui::Command::addTo()) to a menu or toolbar.
 *
 * Now, the implementation of the slots of MainWindow can be done in the method \a activated() of subclasses of Command instead.
 *
 * For example, the implementation of the "Open file" command can be done as follows.
 * \code
 * class OpenCommand : public Command
 * {
 * public:
 *   OpenCommand() : Command("Std_Open")
 *   {
 *     // set up menu text, status tip, ...
 *     sMenuText     = "&Open";
 *     sToolTipText  = "Open a file";
 *     sWhatsThis    = "Open a file";
 *     sStatusTip    = "Open a file";
 *     sPixmap       = "Open"; // name of a registered pixmap
 *     sAccel        = "Shift+P"; // or "P" or "P, L" or "Ctrl+X, Ctrl+C" for a sequence
 *   }
 * protected:
 *   void activated(int)
 *   {
 *     QString filter ... // make a filter of all supported file formats
 *     QStringList FileList = QFileDialog::getOpenFileNames( filter,QString::null, getMainWindow() );
 *     for ( QStringList::Iterator it = FileList.begin(); it != FileList.end(); ++it ) {
 *       getGuiApplication()->open((*it).latin1());
 *     }
 *   }
 * };
 * \endcode
 * An instance of \a OpenCommand must be created and added to the \ref Gui::CommandManager to make the class known to FreeCAD.
 * To see how menus and toolbars can be built go to the @ref workbench.
 *
 * @see Gui::Command, Gui::CommandManager
 */

Esempio dal progetto VTK

Questo è un esempio da VTK, una libreria di visualizzazione 3D utilizzata per presentare dati scientifici, come risultati di elementi finiti e informazioni come nuvola di punti.

Una classe per archiviare una raccolta di coordinate è definita in un file di intestazione C++. La parte superiore del file è commentata e vengono utilizzate alcune parole chiave, come @class, @brief e @sa per indicare parti importanti. All'interno della classe, prima dei prototipi del metodo della classe, un blocco di testo commentato spiega cosa fa la funzione ei suoi argomenti.

Compilazione della documentazione

Flusso di lavoro generale per produrre la documentazione del codice sorgente con Doxygen.

Per generare la documentazione del codice sorgente ci sono due passaggi fondamentali:

  1. Creare un file di configurazione per controllare come Doxygen elaborerà i file sorgente.
  2. Eseguire doxygen su quella configurazione.

Il processo è descritto di seguito.

  • Assicurarsi di avere i programmi doxygen e doxywizard nel proprio sistema. Si consiglia inoltre di avere il programma dot da Graphviz, per generare diagrammi con le relazioni tra classi e spazi dei nomi. Sui sistemi Linux questi programmi possono essere installati dal tuo gestore di pacchetti.
sudo apt install doxygen doxygen-gui graphviz
  • Assicurarsi di essere nella stessa cartella dei tuoi file di origine, o nella directory di livello superiore del tuo albero di origine, se si hanno molti file di origine in diverse sotto cartelle.
cd toplevel-source
  • Eseguire doxygen -g DoxyDoc.cfg per creare un file di configurazione chiamato DoxyDoc.cfg. Se si omette questo nome, il valore predefinito sarà Doxyfile senza estensione.
  • Questo è un grande file di testo semplice che include molte variabili con i loro valori. Nel manuale Doxygen queste variabili sono chiamate "tag". Il file di configurazione e tutti i tag sono ampiamente descritti nella sezione Configurazione del manuale. È possibile aprire il file con qualsiasi editor di testo e modificare il valore di ogni tag secondo necessità. Nello stesso file puoi leggere i commenti che spiegano ciascuno dei tag e i loro valori predefiniti.
DOXYFILE_ENCODING      = UTF-8
PROJECT_NAME           = "My Project"
PROJECT_NUMBER         =
PROJECT_BRIEF          =
PROJECT_LOGO           =
OUTPUT_DIRECTORY       =
CREATE_SUBDIRS         = NO
ALLOW_UNICODE_NAMES    = NO
BRIEF_MEMBER_DESC      = YES
REPEAT_BRIEF           = YES
...
  • Invece di utilizzare un editor di testo, si può avviare doxywizard per modificare più tag contemporaneamente. Con questa interfaccia è possibile definire molte proprietà come informazioni sul progetto, tipo di output (HTML e LaTeX), utilizzo di Graphviz per creare diagrammi, messaggi di avviso da visualizzare, modelli di file (estensioni) da documentare o escludere, filtri di input, intestazioni opzionali e piè di pagina per le pagine generate in HTML, opzioni per output LaTeX, RTF, XML o Docbook e molte altre opzioni.
doxywizard DoxyDoc.cfg
  • Un'altra opzione è creare il file di configurazione da zero e aggiungere solo i tag desiderati con un editor di testo.
  • Dopo aver salvato la configurazione, si può eseguire Doxygen su questo file di configurazione.
doxygen DoxyDoc.cfg
  • La documentazione generata verrà creata all'interno di una cartella denominata toplevel-source/html. Consisterà in molte pagine HTML, immagini PNG per la grafica, fogli di stile a cascata (.css), file Javascript (.js) e potenzialmente molte sotto cartelle con più file a seconda sulla dimensione del codice. Il punto di accesso alla documentazione è index.html, che si può aprire con un browser web.
xdg-open toplevel-source/html/index.html

Se si stanno scrivendo nuove classi, funzioni o un intero nuovo workbench, si consiglia di eseguire periodicamente doxygen per verificare che la documentazione blocchi Markdown e special commands vengano letti correttamente e che tutte le funzioni pubbliche siano completamente documentate. Si prega di leggere anche i suggerimenti per la documentazione che si trovano nel codice sorgente.

Quando si genera la documentazione completa di FreeCAD, non si esegue doxygen direttamente. Invece, il progetto utilizza cmake per configurare l'ambiente di compilazione, quindi make avvia la compilazione dei sorgenti di FreeCAD e della documentazione di Doxygen; questo è spiegato nella pagina documentazione sorgente.

markup di Doxygen

Tutti i comandi di documentazione di Doxygen iniziano con una barra rovesciata \ o un simbolo at @, a scelta. Normalmente si usa la barra rovesciata \, ma occasionalmente si usa @ per migliorare la leggibilità.

I comandi possono avere uno o più argomenti. Nel manuale Doxygen gli argomenti sono descritti come segue.

  • Se vengono utilizzate parentesi con segno minore e maggiore <sharp> l'argomento è una singola parola.
  • Se vengono utilizzate parentesi tonde (round) l'argomento si estende fino alla fine della riga in cui è stato trovato il comando.
  • Se vengono utilizzate le parentesi graffe {curly} l'argomento si estende fino al paragrafo successivo. I paragrafi sono delimitati da una riga vuota o da un indicatore di sezione.
  • Se si usano le parentesi quadre [square] l'argomento è facoltativo.

Alcune delle parole chiave più comuni utilizzate nella documentazione di FreeCAD sono presentate qui.

  • \defgroup <name> (group title) , vedere \defgroup, e Grouping.
  • \ingroup (<groupname> [<groupname> <groupname>]), vedere \ingroup, e Grouping.
  • \addtogroup <name> [(title)], vedere \addtogroup, e Grouping.
  • \author { list of authors }, vedere \author; indica l'autore di questo pezzo di codice.
  • \brief { brief description }, vedere \brief; descrive brevemente la funzione.
  • \file [<name>], vedere \file; documenta un file di origine o di intestazione.
  • \page <name> (title), see \page; inserisce le informazioni in una pagina separata, non direttamente correlata a una specifica classe, file o membro.
  • \package <name>, vedere \package; indica la documentazione per un pacchetto Java (ma è utilizzato anche con Python).
  • \fn (function declaration), vedere \fn; documenta una funzione.
  • \var (variable declaration), vedere \var; documenta una variabile; è equivalente a \fn, \property, e \typedef.
  • \section <section-name> (section title), vedere \section; inizia una sessione.
  • \subsection <subsection-name> (subsection title), vedere \subsection; inizia una sottosessione.
  • \namespace <name>, vedere \namespace; indica le informazioni per uno spazio dei nomi.
  • \cond [(section-label)], e \endcond, vedere \cond; definisce un blocco da documentare o omettere in modo condizionale.
  • \a <word>, vedere \a; visualizza l'argomento in corsivo per dare enfasi.
  • \param [(dir)] <parameter-name> { parameter description }, vedere \param; indica il parametro di una funzione.
  • \return { description of the return value }, vedere \return; specifica il valore restituito.
  • \sa { references }, vedere \sa; stampa "See also".
  • \note { text }, vedere \note; aggiunge un paragrafo da utilizzare come nota.

Supporto al Markdown

A partire da Doxygen 1.8, la sintassi Markdown è riconosciuta dai blocchi di documentazione. Markdown è un linguaggio di formattazione minimalista ispirato all'e-mail di testo semplice che, simile alla sintassi wiki, intende essere semplice e leggibile senza richiedere codice complicato come quello che si trova in HTML, LaTeX o i comandi di Doxygen. Markdown ha guadagnato popolarità con il software libero, specialmente nelle piattaforme online come Github, in quanto consente di creare documentazione senza utilizzare codice complicato. Consultare la sezione Markdown support nel manuale Doxygen per saperne di più. Visitare il sito web di Markdown per saperne di più sull'origine e la filosofia di Markdown.

Doxygen supporta un set standard di istruzioni Markdown, nonché alcune estensioni come Github Markdown.

Di seguito vengono presentati alcuni esempi di formattazione Markdown.

Quello che segue è Markdown standard. 

Ecco il testo per un paragrafo.

Continuiamo con altro testo in un altro paragrafo.

Questa è un'intestazione di livello 1
========================

Questa è un'intestazione di livello 2
------------------------

# Questa è un'intestazione di livello 1

### Questa è l'intestazione di livello 3 #######

> Questa è un blocco di citazione
> su più righe

- Articolo 1

  Altro testo per questo articolo.

- Punto 2
  * voce di elenco nidificata.
  * un altro elemento nidificato.
- Punto 3

1. Primo elemento.
2. Secondo elemento.

*asterisco singolo: enfasi*

 _sottolineature singole_

 **doppio asterisco: enfasi forte**

 __sottolineature doppie__

Questo è un paragrafo normale

    Questo è un blocco di codice

Continuiamo di nuovo con un paragrafo normale.

Usa la funzione `printf()`. `codice` inline.

[Il testo del link](http://example.net/)

![Testo della didascalia](/path/to/img.jpg)

<http://www.example.com>

Le seguenti sono estensioni di Markdown. 

[TOC]

Prima intestazione    | Seconda intestazione
----------------------| ---------------------
Contenuto della Cella | Contenuto della Cella
Contenuto della Cella | Contenuto della Cella 

~~~~~~~~~~~~~{.py}
# A class
class Dummy:
    pass
~~~~~~~~~~~~~

~~~~~~~~~~~~~{.c}
int func(int a, int b) { return a*b; }
~~~~~~~~~~~~~

```
int func(int a, int b) { return a*b; }
```

Analisi dei blocchi della documentazione

Il testo all'interno di uno speciale blocco di documentazione viene analizzato prima di essere scritto nei file di output HTML e LaTeX. Durante l'analisi si verificano i seguenti passaggi:

  • La formattazione Markdown è sostituita dall'HTML corrispondente o da comandi speciali.
  • Vengono eseguiti i comandi speciali all'interno della documentazione. Vedere la sezione Comandi speciali nel manuale per una spiegazione di ciascun comando.
  • Se una riga inizia con degli spazi bianchi seguiti da uno o più asterischi (*) e poi facoltativamente altri spazi bianchi, tutti gli spazi bianchi e gli asterischi vengono rimossi.
  • Tutte le righe vuote risultanti vengono trattate come separatori di paragrafo.
  • I collegamenti vengono creati automaticamente per le parole corrispondenti a classi o funzioni documentate. Se la parola è preceduta da un simbolo di percentuale %, questo simbolo viene rimosso e non viene creato alcun collegamento per la parola.
  • I collegamenti vengono creati quando nel testo vengono trovati determinati schemi. Vedere la sezione Generazione automatica di link nel manuale per ulteriori informazioni.
  • I tag HTML presenti nella documentazione vengono interpretati e convertiti in equivalenti LaTeX per l'output LaTeX. Vedere la sezione Comandi HTML nel manuale per una spiegazione di ciascun tag HTML supportato.

Doxygen con codice Python

Doxygen funziona meglio per linguaggi tipizzati staticamente come C++. Tuttavia, può anche creare documentazione per i file Python.

Esistono due modi per scrivere blocchi di documentazione per Python:

  1. Il modo Pythonico, usando "docstrings", cioè un blocco di testo racchiuso tra '''virgolette triple''' subito dopo la definizione della classe o della funzione.
  2. Il modo Doxygen, inserendo i commenti prima della definizione della classe o della funzione; in questo caso vengono utilizzati i doppi caratteri hash ## per iniziare il blocco di documentazione, e quindi un singolo carattere hash può essere utilizzato nelle righe successive.

Nota:

  • La prima opzione è preferita per rispettare PEP8, pep-0257/ PEP257 e la maggior parte delle linee guida di stile per la scrittura di Python (vedere 1, 2). Si consiglia di utilizzare questo stile se si intende produrre fonti documentate utilizzando Sphinx, che è uno strumento molto comune per documentare il codice Python. Se usi questo stile, Doxygen sarà in grado di estrarre i commenti alla lettera, ma i comandi speciali di Doxygen che iniziano con \ o @ non funzioneranno.
  • La seconda opzione non è il tradizionale stile Python, ma ti permette di usare i comandi speciali di Doxygen come \param e \var.

Primo stile: documentazione Pythonica

Nell'esempio seguente una docstring è all'inizio per spiegare i contenuti generali di questo modulo (file). Quindi le docstring appaiono all'interno delle definizioni di funzione, classe e metodo di classe. In questo modo Doxygen estrarrà i commenti e li presenterà così come sono, senza modifiche. 

'''@package pyexample_a
Documentazione per questo modulo.
Maggiori dettagli.
'''


def func():
    '''Documentazione per una funzione.
    Maggiori dettagli.
    '''
    pass


class PyClass:
    '''Documentazione per una classe.
    Maggiori dettagli.
    '''

    def __init__(self):
        '''Il costruttore.'''
        self._memVar = 0

    def PyMethod(self):
        '''Documentazione per un metodo.'''
        pass

Secondo stile: blocco di documentazione prima del codice

Nell'esempio seguente i blocchi di documentazione iniziano con doppi cancelletti ##. Uno appare all'inizio per spiegare il contenuto generale di questo modulo (file). Quindi ci sono blocchi prima delle definizioni di funzione, classe e metodo di classe e c'è un blocco dopo una variabile di classe. In questo modo, Doxygen estrarrà la documentazione, riconoscerà i comandi speciali @package, @param e @var e formatterà il testo di conseguenza. 

## @package pyexample_b
#  Documentation for this module.
#
#  More details.


## Documentation for a function.
#
#  More details.
def func():
    pass


## Documentation for a class.
#
#  More details.
class PyClass:

    ## The constructor.
    def __init__(self):
        self._memVar = 0

    ## Documentation for a method.
    #  @param self The object pointer.
    def PyMethod(self):
        pass

    ## A class variable.
    classVar = 0
    ## @var _memVar
    #  a member variable

Compilazione della documentazione

La compilazione della documentazione procede come per i sorgenti C++. Se entrambi i file Python, pyexample_a.py e pyexample_b.py, con uno stile di commento distinto si trovano nella stessa directory, verranno elaborati entrambi. 

cd toplevel-source/
doxygen -g
doxygen Doxyfile
xdg-open ./html/index.html

La documentazione dovrebbe mostrare informazioni simili alle seguenti e creare collegamenti appropriati ai singoli moduli e classi. 

Class List
Here are the classes, structs, unions and interfaces with brief descriptions:

N  pyexample_a
   C  PyClass

N  pyexample_b	Documentation for this module
   C  PyClass	Documentation for a class

Conversione dello stile Pythonico in stile Doxygen

Nell'esempio precedente, il file Python commentato in un stile Doxygen mostra informazioni e formattazione più dettagliate per le sue classi, funzioni e variabili. Il motivo è che questo stile consente a Doxygen di estrarre i comandi speciali che iniziano con \ o @, mentre lo stle Pythonico no. Pertanto, sarebbe desiderabile convertire lo stile Pythonico in stile Doxygen prima di compilare la documentazione. Questo è possibile con un programma Python ausiliario chiamato doxypypy. Questo programma è ispirato a un vecchio programma chiamato doxypy, che prende le '''docstrings''' di Python e le converte nei blocchi di commenti Doxygen che iniziano con un doppio hash ##. Doxypypy va oltre, poiché analizza le docstring ed estrae elementi di interesse come variabili e argomenti e persino doctest (codice di esempio nelle docstring).

Doxypypy può essere installato usando pip, il programma di installazione dei pacchetti Python. 

pip3 install --user doxypypy

Se il comando pip viene utilizzato senza l'opzione --user, saranno necessari i privilegi di superutente (root) per installare il pacchetto, ma ciò non è necessario nella maggior parte dei casi; usare i permessi di root solo se sei certo che il pacchetto non entrerà in collisione con i pacchetti forniti dalla tua distribuzione.

Se il pacchetto è stato installato come utente, potrebbe risiedere nella tua home directory, ad esempio in $HOME/.local/bin. Se questa directory non è nel PATH del tuo sistema, il programma non verrà trovato. Pertanto, aggiungere la directory alla variabile PATH, nel file $HOME/.bashrc o nel file $HOME/.profile. 

export PATH="$HOME/.local/bin:$PATH"

In alternativa, si può creare un collegamento simbolico al programma doxypypy, posizionando il collegamento in una directory che è già inclusa nel PATH. 

mkdir -p $HOME/bin
ln -s $HOME/.local/bin/doxypypy $HOME/bin/doxypypy

Una volta che il programma doxypypy è installato e accessibile dal terminale, un file Python con docstring Pythonic può essere riformattato in stile Doxygen con le seguenti istruzioni. Il programma invia il codice riformattato allo standard output, quindi reindirizza questo output a un nuovo file. 

doxypypy -a -c pyexample_pythonic.py > pyexample_doxygen.py

pyexample_pythonic.py 

'''@package pyexample_pythonic
Documentation for this module.
More details go here.
'''


def myfunction(arg1, arg2, kwarg='whatever.'):
    '''
    Does nothing more than demonstrate syntax.

    This is an example of how a Pythonic human-readable docstring can
    get parsed by doxypypy and marked up with Doxygen commands as a
    regular input filter to Doxygen.

    Args:
        arg1:   A positional argument.
        arg2:   Another positional argument.

    Kwargs:
        kwarg:  A keyword argument.

    Returns:
        A string holding the result.

    Raises:
        ZeroDivisionError, AssertionError, & ValueError.

    Examples:
        >>> myfunction(2, 3)
        '5 - 0, whatever.'
        >>> myfunction(5, 0, 'oops.')
        Traceback (most recent call last):
            ...
        ZeroDivisionError: integer division or modulo by zero
        >>> myfunction(4, 1, 'got it.')
        '5 - 4, got it.'
        >>> myfunction(23.5, 23, 'oh well.')
        Traceback (most recent call last):
            ...
        AssertionError
        >>> myfunction(5, 50, 'too big.')
        Traceback (most recent call last):
            ...
        ValueError
    '''
    assert isinstance(arg1, int)
    if arg2 > 23:
        raise ValueError
    return '{0} - {1}, {2}'.format(arg1 + arg2, arg1 / arg2, kwarg)

pyexample_doxygen.py 

##@package pyexample_pythonic
#Documentation for this module.
#More details go here.
#


## @brief     Does nothing more than demonstrate syntax.
#
#    This is an example of how a Pythonic human-readable docstring can
#    get parsed by doxypypy and marked up with Doxygen commands as a
#    regular input filter to Doxygen.
#
#
# @param		arg1	A positional argument.
# @param		arg2	Another positional argument.
#
#
# @param		kwarg	A keyword argument.
#
# @return
#        A string holding the result.
#
#
# @exception		ZeroDivisionError
# @exception		AssertionError
# @exception		ValueError.
#
# @b Examples
# @code
#        >>> myfunction(2, 3)
#        '5 - 0, whatever.'
#        >>> myfunction(5, 0, 'oops.')
#        Traceback (most recent call last):
#            ...
#        ZeroDivisionError: integer division or modulo by zero
#        >>> myfunction(4, 1, 'got it.')
#        '5 - 4, got it.'
#        >>> myfunction(23.5, 23, 'oh well.')
#        Traceback (most recent call last):
#            ...
#        AssertionError
#        >>> myfunction(5, 50, 'too big.')
#        Traceback (most recent call last):
#            ...
#        ValueError
# @endcode
#

def myfunction(arg1, arg2, kwarg='whatever.'):
    assert isinstance(arg1, int)
    if arg2 > 23:
        raise ValueError
    return '{0} - {1}, {2}'.format(arg1 + arg2, arg1 / arg2, kwarg)

Il file originale ha un commento in alto '''@package pyexample_pythonic che indica il modulo o lo spazio dei nomi che viene descritto dal file. Questa parola chiave @package non viene interpretata quando si utilizzano le virgolette triple nel blocco dei commenti.

Nel nuovo file lo stile di commento è cambiato in modo che la riga diventi ##@package pyexample_pythonic, che ora sarà interpretata da Doxygen. Tuttavia, per essere interpretato correttamente, l'argomento deve essere modificato manualmente in modo che corrisponda al nome del nuovo modulo (file); dopo aver fatto questo la riga dovrebbe essere ##@package pyexample_doxygen.

div class="mw-collapsible mw-collapsed toccolours"> pyexample_doxygen.py (la parte superiore viene modificata manualmente, il resto rimane invariato) 

##@package pyexample_doxygen
#Documentation for this module.
#More details go here.
#

Per compilare, creare la configurazione ed eseguire doxygen nella directory di livello superiore che contiene i file. 

cd toplevel-source/
doxygen -g
doxygen Doxyfile
xdg-open ./html/index.html

La documentazione dovrebbe mostrare informazioni simili alle seguenti e creare collegamenti appropriati ai singoli moduli. 

Namespace List
Here is a list of all documented namespaces with brief descriptions:

 N  pyexample_doxygen	Documentation for this module
 N  pyexample_pythonic

Conversione immediata dello stile del commento

Nell'esempio precedente, la conversione dei blocchi di documentazione è stata eseguita manualmente con un solo file sorgente. Idealmente si desidera che questa conversione avvenga automaticamente, al volo, con qualsiasi numero di file Python. Per fare ciò, la configurazione Doxygen deve essere modificata di conseguenza.

Per iniziare, non utilizzare direttamente il programma doxypypy; invece, creare il file di configurazione con doxygen -g, quindi modificare il Doxyfile creato e modificare il seguente tag. 

FILTER_PATTERNS        = *.py=doxypypy_filter

Quello che fa è che i file che corrispondono al modello, tutti i file con un'estensione che termina con .py, passeranno attraverso il programma doxypypy_filter. Ogni volta che Doxygen incontra tale file nell'albero dei sorgenti, il nome del file verrà passato come primo argomento a questo programma. 

doxypypy_filter example.py

Il programma doxypypy_filter non esiste di default; dovrebbe essere creato come uno script di shell per eseguire doxypypy con le opzioni appropriate e per prendere un file come primo argomento. 

#!/bin/sh
doxypypy -a -c "$1"

Dopo aver salvato questo script di shell, assicurarsi che abbia i permessi di esecuzione e che si trovi in una directory contenuta nel PATH del tuo sistema. 

chmod a+x doxypypy_filter
mv doxypypy_filter $HOME/bin

Sui sistemi Windows, un file batch può essere utilizzato in modo simile. 

doxypypy -a -c %1

Con questa configurazione impostata, il comando doxygen Doxyfile può essere eseguito per generare la documentazione come di consueto. Per ogni file Python che usa '''virgolette triple''' Pythonic sarà riformattato al volo per usare i commenti in stile ##Doxygen, e poi questi saranno elaborati da Doxygen, che quindi sarà in grado di interpretare i comandi speciali e la sintassi markdown. Il codice sorgente originale non verrà modificato e non è necessario creare alcun file temporaneo con un nome diverso come nella sezione precedente; pertanto, se viene trovata un'istruzione @package example, non è necessario modificarla manualmente.

Nota che i file Python esistenti che usano già lo stile ##doppio cancelletto per i loro blocchi di commenti non saranno influenzati dal filtro doxypypy e saranno processati normalmente da Doxygen.

Flusso di lavoro generale per produrre la documentazione del codice sorgente con Doxygen, quando i file Python vengono filtrati per trasformare i blocchi dei commenti.

Controllo della qualità del codice Python

Per utilizzare la conversione automatica dei blocchi di documentazione è importante che i sorgenti Python originali siano scritti correttamente, seguendo le linee guida Pythonic in PEP8 e PEP257. Un codice scritto in modo approssimativo causerà il fallimento di doxypypy durante l'elaborazione del file, e quindi Doxygen non sarà in grado di formattare correttamente la documentazione.

I seguenti stili di commento non consentiranno l'analisi delle docstring da parte di doxypypy, quindi dovrebbero essere evitati. 

'''@package Bad
'''

def first_f(one, two):

    "Bad comment 1"

    result = one + two
    result_m = one * two
    return result, result_m

def second_f(one, two):
    "Bad comment 2"
    result = one + two
    result_m = one * two
    return result, result_m

def third_f(one, two):
    'Bad comment 3'
    result = one + two
    result_m = one * two
    return result, result_m

def fourth_f(one, two):
    #Bad comment 4
    result = one + two
    result_m = one * two
    return result, result_m

Usa sempre le virgolette triple per le docstring e assicurati che seguano immediatamente la dichiarazione della classe o della funzione.

È anche una buona idea verificare la qualità del tuo codice Python con uno strumento come flake8 (Gitlab ). Flake8 combina principalmente tre strumenti, Pyflakes, Pycodestyle (precedentemente pep8) e /PyCQA/mccabe Controllo della complessità di McCabe, al fine di applicare il corretto stile Pythonic. 

pip install --user flake8
flake8 example.py

Per controllare tutti i file all'interno di un albero dei sorgenti usa find. 

find toplevel-source/ -name '*.py' -exec flake8 {} '+'

Se il progetto lo richiede, alcuni controlli del codice ritenuti troppo severi possono essere ignorati. I codici di errore possono essere consultati nella Documentazione di Pycodestyle. 

find toplevel-source/ -name '*.py' -exec flake8 --ignore=E266,E402,E722,W503 --max-line-length=100 {} '+'

In modo simile, un programma che controlla principalmente che i commenti siano conformi a PEP257 è Pydocstyle. I codici di errore possono essere consultati nella documentazione di Pydocstyle. 

pip install --user pydocstyle
pydocstyle example.py

Usalo anche con find per eseguire controlli docstring su tutti i file sorgente. 

find toplevel-source/ -name '*.py' -exec pydocstyle {} '+'

Documentazione del sorgente con Sphinx

Sphinx è il sistema più popolare per documentare il codice sorgente Python. Tuttavia, poiché le funzioni principali e gli ambienti di lavoro di FreeCAD sono scritti in C++, si è ritenuto che Doxygen fosse uno strumento di documentazione migliore per questo progetto.

Mentre Sphinx può analizzare in modo nativo le docstring Python, analizzare i sorgenti C++ richiede un po' più di lavoro. Il progetto Breathe (Github) è un tentativo di colmare il divario tra Sphinx e Doxygen, al fine di integrare la documentazione del codice sorgente sia Python che C++ nello stesso sistema. Innanzitutto, Doxygen deve essere configurato per produrre un file XML; l'output XML viene quindi letto da Breathe e convertito in input adatto per Sphinx.

Consultare la Guida rapida della documentazione di Breathe per saperne di più su questo processo.

Vedi questa risposta in Stackoverflow per altre alternative alla documentazione del codice C++ e Python insieme nello stesso progetto.

Relazioni

Retrieved from "http://wiki.freecad.org/index.php?title=Doxygen/it&oldid=1297036"