clindoc

克林多克

ASP 文檔框架，從使用者到貢獻者。

安裝

需要Python 3.10

要安裝 Clindoc，您可以從 git 儲存庫克隆它：

git clone https://github.com/Owrel/clindoc.git

然後導航到 Clindoc 目錄：

 cd clindoc

最後，透過執行以下命令安裝該軟體包：

pip install .

用法

要查看 Clindoc 的所有可用選項，您可以運行：

clindoc -h

Clindoc 允許您透過指定不同的選項來建立自訂文件。

基本用法

例如，給定一個如下的資料夾結構：

 sudoku
├── encoding
│   └── sudoku.lp
└── input.lp

您可以使用下列指令產生數獨資料夾的文件（假設您位於 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(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

Python腳本

透過導入 Clindoc 模組並為其提供所需的參數，也可以在 python 腳本中使用 Clindoc。

 import os
from clindoc import Clindoc

print ( os . getcwd ()) # /path/to/clindoc
c = Clindoc ({ 'src_dir' : 'examples/mapf' })
c . build_documentation ()

字典中包含的參數與命令列中可用的選項相同。但是，- 字元必須替換為 _ 和 。應替換為子目錄。例如，以下命令列：

clindoc --contributordoc.hide-code

將導致 python:

 c = Clindoc ({ 'contributordoc' : 
  { 'hide_code' : True }
})
c . build_documentation ()

這可以在建立文件時提供更大的靈活性和自動化，因為它可以整合到現有的 python 腳本和自動化流程中。

檔案“test.py”包含可以使用的不同參數的範例。

作者

波茨坦大學|波塔斯科解決方案