clindoc
1.0.0
Dokumentationsrahmen für ASP, vom Benutzer bis zum Mitwirkenden.
Erfordert Python 3.10
Um Clindoc zu installieren, können Sie es aus dem Git-Repository klonen:
git clone https://github.com/Owrel/clindoc.gitNavigieren Sie dann zum Clindoc-Verzeichnis:
cd clindocInstallieren Sie abschließend das Paket, indem Sie Folgendes ausführen:
pip install .Um alle verfügbaren Optionen für Clindoc anzuzeigen, können Sie Folgendes ausführen:
clindoc -hMit Clindoc können Sie eine benutzerdefinierte Dokumentation erstellen, indem Sie verschiedene Optionen angeben.
Zum Beispiel bei einer Ordnerstruktur wie:
sudoku
├── encoding
│ └── sudoku.lp
└── input.lp
Mit dem folgenden Befehl können Sie eine Dokumentation für den Sudoku-Ordner erstellen (vorausgesetzt, Sie befinden sich im Verzeichnis clindoc/examples/sudoku):
clindoc Richtlinien sind besondere Kommentare, sie sind als solche gekennzeichnet:
%@directive(param_1,...,param_n)oder mit einer optionalen Beschreibung
%@directive(param_1,...,param_n) -> DescriptionNOTIZ
Hier ist der zugehörige Regex-Ausdruck (mit benannten Gruppen):
* @ * (?P< tag_name > [ a - z A - Z ] + ) * ( (?P< parameters > [ ^ - > ] * ) ) * ( - > * (?P< description > [ ^ \ n ] * ) ) ? Es ist möglich, die Codierung nach Abschnitten aufzuteilen. Dazu können Sie die Direktive section/1 hinzufügen, wobei der Name des Abschnitts als Parameter verwendet wird. Zum Beispiel so:
%@section(Constraints) -> List all of the integrity constraints
:- . ..
:- . .. Für ein besseres Verständnis des Codes ist es möglich, eine Definition der verwendeten Variablen anzugeben. Die var Direktive verwendet als eindeutigen Parameter beispielsweise eine Variable (großgeschrieben).
%@var(X) -> X refer the the x axis position Es ist auch möglich, einem Prädikat eine Definition zu geben, mit anderen Worten, was das Prädikat bedeutet, wobei die predicate zwei Argumente benötigt: die Signatur (funktioniert als Bezeichner) und die Standardvariablen. Zum Beispiel (herausgegeben aus dem Sudoku-Beispiel):
%@predicate(sudoku/3,sudoku(X,Y,V) ) -> The cell (`X`, `Y`) has value `V` with `0 Es ist auch möglich, bestimmte Zeilen zu kommentieren, um beispielsweise eine Erklärung darüber hinzuzufügen, was eine bestimmte Zeile tut (ausgegeben aus dem Sudoku-Beispiel):
%- Can't repeat values per row
:- sudoku( X , Y , V ), sudoku( X '' , Y , V ), X ! = X '' . Hier sind alle verfügbaren Optionen:
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 kann auch in einem Python-Skript verwendet werden, indem das Clindoc-Modul importiert und mit den gewünschten Parametern versehen wird.
import os
from clindoc import Clindoc
print ( os . getcwd ()) # /path/to/clindoc
c = Clindoc ({ 'src_dir' : 'examples/mapf' })
c . build_documentation ()Die im Diktat enthaltenen Parameter sind dieselben wie die in der Befehlszeile verfügbaren Optionen. Allerdings muss das - Zeichen durch _ und ersetzt werden. sollte durch ein Unterverzeichnis ersetzt werden. Zum Beispiel die folgende Befehlszeile:
clindoc --contributordoc.hide-codeFührt zu Python:
c = Clindoc ({ 'contributordoc' :
{ 'hide_code' : True }
})
c . build_documentation ()Dies ermöglicht mehr Flexibilität und Automatisierung bei der Erstellung Ihrer Dokumentation, da diese in Ihre vorhandenen Python-Skripte und Automatisierungsprozesse integriert werden kann.
Die Datei „test.py“ enthält Beispiele für verschiedene Parameter, die verwendet werden können.
Universität Potsdam | Potassco-Lösungen
