clindoc
1.0.0
Framework de documentation pour ASP, de l'utilisateur au contributeur.
Nécessite Python 3.10
Pour installer Clindoc, vous pouvez le cloner depuis le dépôt git :
git clone https://github.com/Owrel/clindoc.gitAccédez ensuite au répertoire Clindoc :
cd clindocEnfin, installez le package en exécutant :
pip install .Pour voir toutes les options disponibles pour Clindoc, vous pouvez exécuter :
clindoc -hClindoc vous permet de créer une documentation personnalisée en spécifiant différentes options.
Par exemple, étant donné une structure de dossiers telle que :
sudoku
├── encoding
│ └── sudoku.lp
└── input.lp
Vous pouvez générer de la documentation pour le dossier sudoku avec la commande suivante (en supposant que vous soyez dans le répertoire clindoc/examples/sudoku) :
clindoc Les directives sont des commentaires particuliers, elles sont identifiées comme telles :
%@directive(param_1,...,param_n)ou avec une description facultative
%@directive(param_1,...,param_n) -> DescriptionNOTE
Voici l'expression regex associée (avec les groupes nommés) :
* @ * (?P< tag_name > [ a - z A - Z ] + ) * ( (?P< parameters > [ ^ - > ] * ) ) * ( - > * (?P< description > [ ^ \ n ] * ) ) ? Il est possible de diviser l'encodage par sections, pour cela, vous pouvez ajouter la directive section/1 , où elle prend en paramètre le nom de la section. Par exemple tel :
%@section(Constraints) -> List all of the integrity constraints
:- . ..
:- . .. Il est possible de donner une définition des variables utilisées pour une meilleure compréhension du code, la directive var prend comme paramètre unique une variable (en majuscule), par exemple
%@var(X) -> X refer the the x axis position Il est également possible de donner une définition à un prédicat, en d'autres termes, ce que signifie le prédicat, où la directive predicate prend 2 arguments : la signature (fonctionne comme identifiant) et les variables par défaut. Par exemple (issu de l'exemple du sudoku) :
%@predicate(sudoku/3,sudoku(X,Y,V) ) -> The cell (`X`, `Y`) has value `V` with `0 il est également possible de commenter des lignes spécifiques afin d'ajouter une explication de ce que fait une ligne spécifique, par exemple (issue de l'exemple du sudoku) :
%- Can't repeat values per row
:- sudoku( X , Y , V ), sudoku( X '' , Y , V ), X ! = X '' . Voici toutes les options disponibles :
Clindoc - Generate documentation for ASP files
options:
-h, --help show this help message and exit
Global Clindoc parameters:
--project_name PROJECT_NAME, -p PROJECT_NAME
Name of the project
--src_dir SRC_DIR, -s SRC_DIR
Directory containing the LP files from which to generate the documentation
--description DESCRIPTION, --desc DESCRIPTION
Description of the project
--doc-dir DOC_DIR, -d DOC_DIR
The folder where the documentation in rst format will be generated. If not specified, it will default to [src-dir]/docs/)
--out-dir OUT_DIR, -b OUT_DIR
Directory where Sphinx will output the generated documentation (if not specified, defaults to [src-dir]/docs/build)
--builder BUILDER Sphinx output format parameter (refer to parameter builder sphinx. Can be any builder supported by Sphinx)
--clean (flag) remove [doc-dir] and [out-dir] before running. Please be sure that you saved any hand-made modification
--no-sphinx-build (flag,debug) skip Sphinx build
--no-rst-build (flag,debug) skip rst build section
--conf-path CONF_PATH
Path to a configuration file (json format). It can be created from the --dump-conf [path_to_conf] command. Any parameters entered in the command line will be ignored.
--dump-conf DUMP_CONF
Path of a file where the configuration will be dumped. The json file will include all of the configuration you've entered in the command line. It can be used later as default configuration using --path-conf [path_to_conf]
-v, --version Print the version and exit
User Documentation parameters:
--userdoc.exclude (flag) component will be excluded from the documentation
Contributor Documentation parameters:
--contributordoc.exclude
(flag) component will be excluded from the documentation
--contributordoc.group-by CONTRIBUTORDOC.GROUP_BY
How the contributor documentation will group the different elements. "section" or "type"
--contributordoc.hide-uncommented
(flag) hide non-commented or non-defined var, rules...
--contributordoc.hide-code
(flag) hide source code
Dependency graph parameters:
--dependencygraph.exclude
(flag) component will be excluded from the documentation
--dependencygraph.format DEPENDENCYGRAPH.FORMAT
Format of the graphs
Source files parameters:
--source.exclude (flag) component will be excluded from the documentation
--source.exclude-file [SOURCE.EXCLUDE_FILE ...]
source file(s) that will be excluded from source documentation section
KRR@UP - https://github.com/krr-up
Clindoc peut également être utilisé dans un script python en important le module Clindoc et en lui fournissant les paramètres souhaités.
import os
from clindoc import Clindoc
print ( os . getcwd ()) # /path/to/clindoc
c = Clindoc ({ 'src_dir' : 'examples/mapf' })
c . build_documentation ()Les paramètres contenus dans le dict sont les mêmes que les options disponibles dans la ligne de commande. Cependant, le caractère - doit être remplacé par _ et . doit être remplacé par un sous-répertoire. Par exemple, la ligne de commande suivante :
clindoc --contributordoc.hide-codeLe résultat sera python :
c = Clindoc ({ 'contributordoc' :
{ 'hide_code' : True }
})
c . build_documentation ()Cela permet plus de flexibilité et d'automatisation lors de la création de votre documentation, car elle peut être intégrée à vos scripts Python et processus d'automatisation existants.
Le fichier "test.py" contient des exemples de différents paramètres pouvant être utilisés.
Université de Potsdam | Solutions Potasso
