Загрузка clindoc - Загрузка исходного кода clindoc

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 -h

Clindoc позволяет создавать собственную документацию, указывая различные параметры.

Основное использование

Например, при такой структуре папок:

 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(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

Параметры

Вот все возможные варианты:

 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 ()

Параметры, содержащиеся в dict, такие же, как параметры, доступные в командной строке. Однако символ - необходимо заменить на _ и . должен быть заменен подкаталогом. Например, следующая командная строка:

clindoc --contributordoc.hide-code

Результатом будет питон:

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

Это обеспечивает большую гибкость и автоматизацию при создании документации, поскольку ее можно интегрировать в существующие сценарии Python и процессы автоматизации.

Файл «test.py» содержит примеры различных параметров, которые можно использовать.