clindoc
1.0.0
ユーザーから貢献者までの ASP のドキュメント フレームワーク。
Python 3.10が必要です
Clindoc をインストールするには、git リポジトリからクローンを作成します。
git clone https://github.com/Owrel/clindoc.git次に、Clindoc ディレクトリに移動します。
cd clindoc最後に、以下を実行してパッケージをインストールします。
pip install .Clindoc で使用可能なオプションをすべて表示するには、次のコマンドを実行します。
clindoc -hClindoc では、さまざまなオプションを指定してカスタム ドキュメントを作成できます。
たとえば、次のようなフォルダー構造があるとします。
sudoku
├── encoding
│ └── sudoku.lp
└── input.lp
次のコマンドを使用して、sudoku フォルダーのドキュメントを生成できます ( clindoc/examples/sudoku ディレクトリにいると仮定します)。
clindoc ディレクティブは特別なコメントであり、次のように識別されます。
%@directive(param_1,...,param_n)またはオプションの説明付き
%@directive(param_1,...,param_n) -> Description注記
関連する正規表現 (名前付きグループを含む) は次のとおりです。
* @ * (?P< tag_name > [ a - z A - Z ] + ) * ( (?P< parameters > [ ^ - > ] * ) ) * ( - > * (?P< description > [ ^ \ n ] * ) ) ?エンコードをセクションごとに分割することができます。そのためには、セクションの名前をパラメータとして受け取るディレクティブsection/1を追加します。たとえば次のようなものです。
%@section(Constraints) -> List all of the integrity constraints
:- . ..
:- . ..コードをよりよく理解するために使用される変数の定義を与えることができます。var ディレクティブvar 、一意のパラメーターとして変数 (大文字) を受け取ります。
%@var(X) -> X refer the the x axis position述語に定義、つまり述語が何を意味するかを指定することもできます。 predicateディレクティブは 2 つの引数、署名 (識別子として機能) とデフォルト変数を受け取ります。例 (数独の例から得たもの):
%@predicate(sudoku/3,sudoku(X,Y,V) ) -> The cell (`X`, `Y`) has value `V` with `0 たとえば、特定の行が何を行っているかの説明を追加するために、特定の行にコメントを付けることもできます (数独の例から発行)。
%- Can't repeat values per row
:- sudoku( X , Y , V ), sudoku( X '' , Y , V ), X ! = X '' . 利用可能なすべてのオプションは次のとおりです。
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 モジュールをインポートし、必要なパラメーターを指定することで、Clindoc を Python スクリプトで使用することもできます。
import os
from clindoc import Clindoc
print ( os . getcwd ()) # /path/to/clindoc
c = Clindoc ({ 'src_dir' : 'examples/mapf' })
c . build_documentation ()dict に含まれるパラメーターは、コマンド ラインで使用できるオプションと同じです。ただし、- 文字は _ と に置き換える必要があります。サブディレクトリに置き換える必要があります。たとえば、次のコマンドライン:
clindoc --contributordoc.hide-code結果はPythonになります:
c = Clindoc ({ 'contributordoc' :
{ 'hide_code' : True }
})
c . build_documentation ()これにより、既存の Python スクリプトや自動化プロセスに統合できるため、ドキュメント作成時の柔軟性と自動化が向上します。
ファイル「test.py」には、使用できるさまざまなパラメータの例が含まれています。
ポツダム大学 |ポタスコソリューション
