clindoc
1.0.0
Estrutura de documentação para ASP, do usuário ao contribuidor.
Requer Python 3.10
Para instalar o Clindoc, você pode cloná-lo no repositório git:
git clone https://github.com/Owrel/clindoc.gitEm seguida, navegue até o diretório Clindoc:
cd clindocPor fim, instale o pacote executando:
pip install .Para ver todas as opções disponíveis para Clindoc, você pode executar:
clindoc -hClindoc permite criar documentação personalizada especificando diferentes opções.
Por exemplo, dada uma estrutura de pastas como:
sudoku
├── encoding
│ └── sudoku.lp
└── input.lp
Você pode gerar documentação para a pasta sudoku com o seguinte comando (supondo que você esteja no diretório clindoc/examples/sudoku):
clindoc As diretivas são comentários especiais, são identificadas como tal:
%@directive(param_1,...,param_n)ou com uma descrição opcional
%@directive(param_1,...,param_n) -> DescriptionOBSERVAÇÃO
Aqui está a expressão regex associada (com grupos nomeados):
* @ * (?P< tag_name > [ a - z A - Z ] + ) * ( (?P< parameters > [ ^ - > ] * ) ) * ( - > * (?P< description > [ ^ \ n ] * ) ) ? É possível dividir a codificação por seções, para isso pode-se adicionar a diretiva section/1 , onde toma como parâmetro o nome da seção. Por exemplo, tal:
%@section(Constraints) -> List all of the integrity constraints
:- . ..
:- . .. É possível dar uma definição das variáveis utilizadas para um melhor entendimento do código, a diretiva var leva como parâmetro único uma variável (em maiúscula), por exemplo
%@var(X) -> X refer the the x axis position Também é possível dar uma definição a um predicado, ou seja, o que significa o predicado, onde a diretiva predicate recebe 2 argumentos: a assinatura (funciona como identificador) e as variáveis padrão. Por exemplo (emitido a partir do exemplo do sudoku):
%@predicate(sudoku/3,sudoku(X,Y,V) ) -> The cell (`X`, `Y`) has value `V` with `0 também é possível comentar linhas específicas para adicionar explicações sobre o que uma linha específica está fazendo, por exemplo (emitida no exemplo do sudoku):
%- Can't repeat values per row
:- sudoku( X , Y , V ), sudoku( X '' , Y , V ), X ! = X '' . Aqui estão todas as opções disponíveis:
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 também pode ser usado em um script python importando o módulo Clindoc e fornecendo-lhe os parâmetros desejados.
import os
from clindoc import Clindoc
print ( os . getcwd ()) # /path/to/clindoc
c = Clindoc ({ 'src_dir' : 'examples/mapf' })
c . build_documentation ()Os parâmetros contidos no dict são iguais às opções disponíveis na linha de comando. No entanto, o caractere - deve ser substituído por _ e . deve ser substituído por um subdiretório. Por exemplo, a seguinte linha de comando:
clindoc --contributordoc.hide-codeResultará em python:
c = Clindoc ({ 'contributordoc' :
{ 'hide_code' : True }
})
c . build_documentation ()Isso permite mais flexibilidade e automação ao criar sua documentação, pois ela pode ser integrada aos seus scripts Python e processos de automação existentes.
O arquivo "test.py" contém exemplos de diferentes parâmetros que podem ser usados.
Universidade de Potsdam | Soluções Potasco
