clindoc
1.0.0
Marco de documentación para ASP, de usuario a colaborador.
Requiere Python 3.10
Para instalar Clindoc, puedes clonarlo desde el repositorio de git:
git clone https://github.com/Owrel/clindoc.gitLuego navegue hasta el directorio de Clindoc:
cd clindocFinalmente, instale el paquete ejecutando:
pip install .Para ver todas las opciones disponibles para Clindoc, puede ejecutar:
clindoc -hClindoc le permite crear documentación personalizada especificando diferentes opciones.
Por ejemplo, dada una estructura de carpetas como:
sudoku
├── encoding
│ └── sudoku.lp
└── input.lp
Puede generar documentación para la carpeta sudoku con el siguiente comando (suponiendo que esté en el directorio clindoc/examples/sudoku):
clindoc Las directivas son comentarios especiales, se identifican como tales:
%@directive(param_1,...,param_n)o con una descripción opcional
%@directive(param_1,...,param_n) -> DescriptionNOTA
Aquí está la expresión regular asociada (con grupos con nombre):
* @ * (?P< tag_name > [ a - z A - Z ] + ) * ( (?P< parameters > [ ^ - > ] * ) ) * ( - > * (?P< description > [ ^ \ n ] * ) ) ? Es posible dividir la codificación por secciones, para ello se puede agregar la directiva section/1 , donde toma como parámetro el nombre de la sección. Por ejemplo tales:
%@section(Constraints) -> List all of the integrity constraints
:- . ..
:- . .. Es posible dar una definición de las variables utilizadas para una mejor comprensión del código, la directiva var toma como parámetro único una variable (en mayúscula), por ejemplo
%@var(X) -> X refer the the x axis position También es posible darle una definición a un predicado, en otras palabras, qué significa el predicado, donde la directiva predicate toma 2 argumentos: la firma (funciona como identificador) y las variables predeterminadas. Por ejemplo (emitido del ejemplo de sudoku):
%@predicate(sudoku/3,sudoku(X,Y,V) ) -> The cell (`X`, `Y`) has value `V` with `0 También es posible comentar líneas específicas para agregar una explicación de lo que hace una línea específica, por ejemplo (publicado en el ejemplo de sudoku):
%- Can't repeat values per row
:- sudoku( X , Y , V ), sudoku( X '' , Y , V ), X ! = X '' . Aquí tienes todas las opciones 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 también se puede utilizar en un script de Python importando el módulo Clindoc y proporcionándole los parámetros deseados.
import os
from clindoc import Clindoc
print ( os . getcwd ()) # /path/to/clindoc
c = Clindoc ({ 'src_dir' : 'examples/mapf' })
c . build_documentation ()Los parámetros contenidos en el dict son los mismos que las opciones disponibles en la línea de comando. Sin embargo, el carácter - debe reemplazarse por _ y . debe ser reemplazado por un subdirectorio. Por ejemplo, la siguiente línea de comando:
clindoc --contributordoc.hide-codeResultará en Python:
c = Clindoc ({ 'contributordoc' :
{ 'hide_code' : True }
})
c . build_documentation ()Esto permite una mayor flexibilidad y automatización al crear su documentación, ya que puede integrarse en sus scripts de Python y procesos de automatización existentes.
El archivo "test.py" contiene ejemplos de diferentes parámetros que se pueden utilizar.
Universidad de Potsdam | Soluciones Potasco
