Source documentation/fr: Difference between revisions

From FreeCAD Documentation
(Created page with "Suivez ensuite les mêmes étapes que pour compiler FreeCAD, comme décrit à la page Compiler sous Unix, et résumées ici pour plus de commodité. * Obt...")
No edit summary
 
(68 intermediate revisions by 5 users not shown)
Line 1: Line 1:
<languages/>
<languages/>
{{docnav/fr|[[Extra python modules/fr|Modules Python supplémentaires]]|[[List of Commands/fr|Liste des commandes]]}}


{{Docnav/fr
Le code source de FreeCAD est commenté pour permettre la génération automatique de documentation HTML à l'aide de [http://www.doxygen.org Doxygen], un système de documentation de code source populaire. Doxygen peut documenter les parties C++ et Python de FreeCAD.
|[[Extra_python_modules/fr|Modules Python supplémentaires]]
|[[Contributors/fr|Contributeurs]]
}}


{{TOCright}}
La documentation source en ligne est située sur [http://www.freecadweb.org/api/ web]. Veuillez noter que cette documentation n'est pas toujours conservée à ce jour. si vous avez des questions urgentes sur le code, veuillez demander dans la section développeurs du [https://forum.freecadweb.org/index.php FreeCAD forum].

== Présentation ==
Le code source de FreeCAD est commenté pour permettre la génération automatique de documentation HTML à l'aide de [[Doxygen/fr|Doxygen]], un système de documentation de code source populaire. Doxygen peut documenter les parties C++ et Python de FreeCAD, générant ainsi des pages HTML avec des hyperliens vers chaque fonction et classe documentées.

La documentation est hébergée en ligne sur le [https://freecad.github.io/SourceDoc/ site web de l'API FreeCAD]. Veuillez noter que cette documentation n'est pas toujours maintenue à jour. Si vous avez besoin de plus de détails, téléchargez le dernier code source de FreeCAD et compilez vous-même la documentation. Si vous avez des questions urgentes sur le code, veuillez les poser dans la section développeurs du [https://forum.freecadweb.org/index.php FreeCAD forum].

La compilation de la documentation de l'API suit les mêmes étapes générales que la compilation de l'exécutable FreeCAD, comme indiqué dans la page de [[Compile_on_Linux/fr|compilation sous Linux]].

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

{{Caption|Flux de travail général pour compiler la documentation de programmation de FreeCAD. Les packages Doxygen et Graphviz doivent être dans le système, ainsi que le code source FreeCAD lui-même. CMake configure le système de telle sorte qu'avec une seule instruction make, la documentation de l'ensemble du projet soit compilée dans de nombreux fichiers HTML avec des diagrammes.}}


== Compilation de la documentation ==
== Compilation de la documentation ==


=== Documentation complète ===
Si vous avez installé Doxygen, il est très facile de construire la documentation. Installez également [https://www.graphviz.org/ Graphviz] pour pouvoir produire des diagrammes montrant les relations entre différentes classes et bibliothèques dans le code FreeCAD. Graphviz est également utilisé par [[Std DependencyGraph/fr|graphe de dépendance]] de FreeCAD pour montrer les relations entre différents objets.

Si vous avez installé Doxygen, il est très facile de construire la documentation. Installez également [https://www.graphviz.org/ Graphviz] pour pouvoir produire des diagrammes montrant les relations entre différentes classes et bibliothèques dans le code FreeCAD. Graphviz est également utilisé par le [[Std_DependencyGraph/fr|graphe de dépendance]] de FreeCAD pour montrer les relations entre différents objets.
{{Code|code=
{{Code|code=
sudo apt install doxygen graphviz
sudo apt install doxygen graphviz
}}
}}


Suivez ensuite les mêmes étapes que pour compiler FreeCAD, comme décrit à la page [[CompileOnUnix/fr|Compiler sous Unix]], et résumées ici pour plus de commodité.
Suivez ensuite les mêmes étapes que pour compiler FreeCAD, comme décrit à la page [[Compile_on_Linux/fr|Compiler sous Linux]], et résumées ici pour plus de commodité.
* Obtenez le code source de FreeCAD et placez-le dans son propre répertoire {{incode|freecad-source}}.
* Récupérez le code source de FreeCAD et placez-le dans son propre répertoire {{incode|freecad-source}}.
* Créez un autre répertoire {{incode|freecad-build}} dans lequel vous compilerez FreeCAD et sa documentation.
* Créez un autre répertoire {{incode|freecad-build}} dans lequel vous compilerez FreeCAD et sa documentation.
* Configurez les sources avec {{incode|cmake}}, en vous assurant d'indiquer le répertoire source et de spécifier les options requises pour votre construction.
* Configurez les sources avec {{incode|cmake}}, en vous assurant d'indiquer le répertoire source et de spécifier les options requises pour votre compilation.
* Déclenchez la création de la documentation avec {{incode|make}}.
* Lancer la création de la documentation avec {{incode|make}}.
{{Code|code=
{{Code|code=
git clone https://github.com/FreeCAD/FreeCAD.git freecad-source
git clone https://github.com/FreeCAD/FreeCAD.git freecad-source
Line 25: Line 40:
}}
}}


Pendant que vous êtes dans le répertoire de compilation, émettez les instructions suivantes pour ne créer que la documentation.
While you are inside the build directory issue the following instruction to create only the documentation.
{{Code|code=
{{Code|code=
make -j$(nproc --ignore=2) DevDoc
make -j$(nproc --ignore=2) DevDoc
}}
}}
Comme mentionné dans [[Compiling_(Speeding_up)/fr|Compilation (Accélération)]], l'option {{incode|-j}} définit le nombre de cœurs de processeur utilisés pour la compilation. Les fichiers de documentation résultants apparaîtront dans le répertoire
<div class="mw-translate-fuzzy">
et consultez les fichiers HTML résultants à partir de '''Doc/SourceDocu/html/index.html'''.
</div>
{{Code|code=
{{Code|code=
freecad-build/doc/SourceDocu/html/
freecad-build/doc/SourceDocu/html/
}}
}}


The point of entrance to the documentation is the {{incode|index.html}} file, which you can open with a web browser:
Le point d’entrée de la documentation est le fichier {{incode|index.html}}, que vous pouvez ouvrir avec un navigateur Web:
{{Code|code=
{{Code|code=
xdg-open freecad-build/doc/SourceDocu/html/index.html
xdg-open freecad-build/doc/SourceDocu/html/index.html
}}
}}


La cible {{incode|DevDoc}} générera une quantité importante de données, environ 5 Go de nouveaux fichiers, en raison notamment des diagrammes créés par Graphviz.
<div class="mw-translate-fuzzy">
La cible DevDoc ci-dessus permettra, si graphviz est installé sur votre système, de générer un volume de données supérieur à 2 Go. Une version alternative plus petite (~ 500 Mo), qui est la version utilisée sur http://www.freecadweb.org/api/ peut également être générée en saisissant à la place :
</div>


=== Documentation réduite ===
An alternative, smaller version of the documentation which takes only around 600 MB can be generated with a different target. This is the version displayed on the [http://www.freecadweb.org/api/ FreeCAD API website].

La documentation complète utilise environ 3 Gb d'espace disque. Une autre version plus petite de la documentation, qui ne nécessite qu'environ 600 MB, peut être générée avec une cible différente. Ceci est la version affichée sur le [https://freecad.github.io/SourceDoc/ site Web de l'API FreeCAD].
{{Code|code=
{{Code|code=
make -j$(nproc --ignore=2) WebDoc
make -j$(nproc --ignore=2) WebDoc
}}
}}


La documentation sur le [https://freecad.github.io/SourceDoc/ site Web de l'API FreeCAD] est produite automatiquement à partir de https://github.com/FreeCAD/SourceDoc. Tout le monde peut le reconstruire et soumettre un pull request :
<div class="mw-translate-fuzzy">
Comme alternative, la doc est générée de temps en temps, et accessible sur sourceforge [http://free-cad.sf.net/SrcDocu/index.html ici].
</div>


* forkez le repo sur https://github.com/FreeCAD/SourceDoc
[https://iesensor.com/FreeCADDoc/0.16-dev/ FreeCAD 0.16 development] documentation built by [http://forum.freecadweb.org/viewtopic.php?t=12613 qingfeng.xia].
* sur votre machine: clonez le code FreeCAD (si vous ne l'avez pas encore fait), créez un répertoire de construction pour le document et clonez le référentiel SourceDoc ci-dessus à l'intérieur. Ce SourceDoc sera mis à jour lorsque vous reconstruirez le document et vous pourrez valider et pousser les résultats par la suite:
{{Code|code=
git clone https://github.com/FreeCAD/FreeCAD
cd FreeCAD
mkdir build
cd build
mkdir -p doc/SourceDocu/html
cd doc/SourceDocu/html
git clone your-fork-url
cd ../../..
cmake -DBUILD_QT5=ON -DPYTHON_EXECUTABLE=/usr/bin/python3 ..
make WebDoc
cd doc/SourceDocu/html
git commit
git push
}}
* Accédez à votre fork en ligne et créez un pull request.


== Autres versions ==
<div class="mw-translate-fuzzy">
Voici une autre [https://iesensor.com/FreeCADDoc/0.19/ documentation FreeCAD 0.19dev Doxygen] ainsi qu'une version précédente [https://iesensor.com/FreeCADDoc/0.16-dev/ 0.16dev_documentation], générée par [http://forum.freecadweb.org/viewtopic.php?t=12613 qingfeng.xia].
Documentation de la [https://iesensor.com/FreeCADDoc/0.19/ version développement FreeCAD 0.19] construite par [http://forum.freecadweb.org/viewtopic.php?t=12613 qingfeng.xia].
</div>


== Intégrer la documentation Coin3D ==
<div class="mw-translate-fuzzy">
=== Intégrer la documentation Coin3D ===
</div>


Sur les systèmes Unix, il est possible de lier la documentation source Coin3D avec FreeCAD. Cela facilite la navigation et complète les diagrammes d'héritage pour les classes dérivées de Coin.
<div class="mw-translate-fuzzy">
Sur les systèmes Unix, il est possible de lier les documents sources '''Coin3D''' avec '''FreeCAD'''.


* Installez le {{incode|libcoin-doc}}, {{incode|libcoin80-doc}}, ou un paquetage similaire.
Il permet une navigation plus facile dans l'arborescence des diagrammes, pour les classes '''Coin''' dérivées.
* Décompressez l'archive {{incode|coin.tar.gz}} située dans {{incode|/usr/share/doc/libcoin-doc/html}}; les fichiers sont peut-être déjà décompressés dans votre système.
</div>
* Générez à nouveau la documentation source.


Si vous n'installez pas le package de documentation pour Coin, les liens seront générés pour accéder à la documentation en ligne à l'adresse [https://coin3d.bitbucket.io/Coin/ BitBucket]. Cela se produira si un fichier de balise Doxygen peut être téléchargé au moment de la configuration avec {{incode|wget}}.
<div class="mw-translate-fuzzy">
* Sur les systèmes Debian et dérivés :
: - Installez le paquet '''libcoin60-doc'''.
: - Décompressez le fichier '''/usr/share/doc/libcoin60-doc/html/coin.tag.gz'''.
: - Régénérer le source de la documentation.
: Vous êtes prêt pour la navigation hors ligne.
</div>


== Utiliser Doxygen ==
<div class="mw-translate-fuzzy">
* Si vous ne voulez pas, ou ne pouvez pas installer '''Coin doc package''', les liens seront générés pour accéder à '''Coin doc''' en ligne, sur '''[http://doc.coin3d.org/ doc.coin3D.org]''', si le fichier '''doxygen tag''' peut être téléchargé au moment de la configuration (wget).
</div>


Voir la page [[Doxygen/fr|Doxygen]] pour une explication détaillée sur la façon de commenter le code source C++ et Python afin qu'il puisse être traité par Doxygen pour créer automatiquement la documentation.
<div class="mw-translate-fuzzy">
== Comment intégrer doxygen dans le code source de FreeCAD ==
{{VeryImportantMessage|Ceci est un travail en cours. Voyez [[Doxygen]]}}
Exemple de page complète doxygen : (d'un autre projet)
</div>


Basiquement, un bloc de commentaires commençant par {{incode|/**}} ou {{incode|///}} pour C++, ou {{incode|##}} pour Python, doit apparaître avant chaque définition de classe ou de fonction, afin qu’elle soit sélectionnée par Doxygen. De [[Doxygen/fr#Balisage_Doxygen|nombreuses commandes spéciales]], commençant par {{incode|\}} ou {{incode|@}}, peuvent être utilisées pour définir des parties du code et formater la sortie. La [[Doxygen/fr#Support_de_Markdown|syntaxe Markdown]] est également comprise dans le bloc de commentaires, ce qui facilite la mise en évidence de certaines parties de la documentation.
This section explains how to comment your source code so that it can be processed by Doxygen to automatically create the documentation.
{{Code|code=
/**
* Returns the name of the workbench object.
*/
std::string name() const;


/**
This is an example of how source code is documented. It looks into the source code of VTK, a 3D visualization library used to present multi-physics simulation results.
* Set the name to the workbench object.
*/
void setName(const std::string&);


/// remove the added TaskWatcher
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}}, {{incode|@sa}}, and {{incode|@par}} to indicate important parts. Inside the class, before a function is called, a block of commented text explains what the function does, and its arguments.
void removeTaskWatcher(void);
}}


<div class="mw-translate-fuzzy">
source : https://github.com/Kitware/VTK/blob/master/Common/Core/vtkArrayCoordinates.h
</div>


{{Docnav/fr
{{docnav/fr|[[Extra python modules/fr|Modules Python supplémentaires]]|[[List of Commands/fr|Liste des commandes]]}}
|[[Extra_python_modules/fr|Modules Python supplémentaires]]

|[[Contributors/fr|Contributeurs]]
{{Userdocnavi/fr}}
}}


{{Userdocnavi{{#translation:}}}}
[[Category:Developer Documentation/fr]]
[[Category:Developer Documentation{{#translation:}}]]
{{clear}}
{{clear}}

Latest revision as of 10:13, 13 November 2021

Présentation

Le code source de FreeCAD est commenté pour permettre la génération automatique de documentation HTML à l'aide de Doxygen, un système de documentation de code source populaire. Doxygen peut documenter les parties C++ et Python de FreeCAD, générant ainsi des pages HTML avec des hyperliens vers chaque fonction et classe documentées.

La documentation est hébergée en ligne sur le site web de l'API FreeCAD. Veuillez noter que cette documentation n'est pas toujours maintenue à jour. Si vous avez besoin de plus de détails, téléchargez le dernier code source de FreeCAD et compilez vous-même la documentation. Si vous avez des questions urgentes sur le code, veuillez les poser dans la section développeurs du FreeCAD forum.

La compilation de la documentation de l'API suit les mêmes étapes générales que la compilation de l'exécutable FreeCAD, comme indiqué dans la page de compilation sous Linux.

Flux de travail général pour compiler la documentation de programmation de FreeCAD. Les packages Doxygen et Graphviz doivent être dans le système, ainsi que le code source FreeCAD lui-même. CMake configure le système de telle sorte qu'avec une seule instruction make, la documentation de l'ensemble du projet soit compilée dans de nombreux fichiers HTML avec des diagrammes.

Compilation de la documentation

Documentation complète

Si vous avez installé Doxygen, il est très facile de construire la documentation. Installez également Graphviz pour pouvoir produire des diagrammes montrant les relations entre différentes classes et bibliothèques dans le code FreeCAD. Graphviz est également utilisé par le graphe de dépendance de FreeCAD pour montrer les relations entre différents objets.

sudo apt install doxygen graphviz

Suivez ensuite les mêmes étapes que pour compiler FreeCAD, comme décrit à la page Compiler sous Linux, et résumées ici pour plus de commodité.

  • Récupérez le code source de FreeCAD et placez-le dans son propre répertoire freecad-source.
  • Créez un autre répertoire freecad-build dans lequel vous compilerez FreeCAD et sa documentation.
  • Configurez les sources avec cmake, en vous assurant d'indiquer le répertoire source et de spécifier les options requises pour votre compilation.
  • Lancer la création de la documentation avec make.
git clone https://github.com/FreeCAD/FreeCAD.git freecad-source
mkdir freecad-build
cd freecad-build
cmake -DBUILD_QT5=ON -DPYTHON_EXECUTABLE=/usr/bin/python3 ../freecad-source

Pendant que vous êtes dans le répertoire de compilation, émettez les instructions suivantes pour ne créer que la documentation.

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

Comme mentionné dans Compilation (Accélération), l'option -j définit le nombre de cœurs de processeur utilisés pour la compilation. Les fichiers de documentation résultants apparaîtront dans le répertoire

freecad-build/doc/SourceDocu/html/

Le point d’entrée de la documentation est le fichier index.html, que vous pouvez ouvrir avec un navigateur Web:

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

La cible DevDoc générera une quantité importante de données, environ 5 Go de nouveaux fichiers, en raison notamment des diagrammes créés par Graphviz.

Documentation réduite

La documentation complète utilise environ 3 Gb d'espace disque. Une autre version plus petite de la documentation, qui ne nécessite qu'environ 600 MB, peut être générée avec une cible différente. Ceci est la version affichée sur le site Web de l'API FreeCAD.

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

La documentation sur le site Web de l'API FreeCAD est produite automatiquement à partir de https://github.com/FreeCAD/SourceDoc. Tout le monde peut le reconstruire et soumettre un pull request :

  • forkez le repo sur https://github.com/FreeCAD/SourceDoc
  • sur votre machine: clonez le code FreeCAD (si vous ne l'avez pas encore fait), créez un répertoire de construction pour le document et clonez le référentiel SourceDoc ci-dessus à l'intérieur. Ce SourceDoc sera mis à jour lorsque vous reconstruirez le document et vous pourrez valider et pousser les résultats par la suite:
git clone https://github.com/FreeCAD/FreeCAD
cd FreeCAD
mkdir build
cd build
mkdir -p doc/SourceDocu/html
cd doc/SourceDocu/html
git clone your-fork-url
cd ../../..
cmake -DBUILD_QT5=ON -DPYTHON_EXECUTABLE=/usr/bin/python3 ..
make WebDoc
cd doc/SourceDocu/html
git commit
git push
  • Accédez à votre fork en ligne et créez un pull request.

Autres versions

Documentation de la version développement FreeCAD 0.19 construite par qingfeng.xia.

Intégrer la documentation Coin3D

Sur les systèmes Unix, il est possible de lier la documentation source Coin3D avec FreeCAD. Cela facilite la navigation et complète les diagrammes d'héritage pour les classes dérivées de Coin.

  • Installez le libcoin-doc, libcoin80-doc, ou un paquetage similaire.
  • Décompressez l'archive coin.tar.gz située dans /usr/share/doc/libcoin-doc/html; les fichiers sont peut-être déjà décompressés dans votre système.
  • Générez à nouveau la documentation source.

Si vous n'installez pas le package de documentation pour Coin, les liens seront générés pour accéder à la documentation en ligne à l'adresse BitBucket. Cela se produira si un fichier de balise Doxygen peut être téléchargé au moment de la configuration avec wget.

Utiliser Doxygen

Voir la page Doxygen pour une explication détaillée sur la façon de commenter le code source C++ et Python afin qu'il puisse être traité par Doxygen pour créer automatiquement la documentation.

Basiquement, un bloc de commentaires commençant par /** ou /// pour C++, ou ## pour Python, doit apparaître avant chaque définition de classe ou de fonction, afin qu’elle soit sélectionnée par Doxygen. De nombreuses commandes spéciales, commençant par \ ou @, peuvent être utilisées pour définir des parties du code et formater la sortie. La syntaxe Markdown est également comprise dans le bloc de commentaires, ce qui facilite la mise en évidence de certaines parties de la documentation.

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