الصفحة الرئيسية>كود مصدر ASP>فئات أخرى
تنزيل

كليندوك

إطار التوثيق لـ ASP، من المستخدم إلى المساهم.

تثبيت

يتطلب بايثون 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

ملحوظة

إليك تعبير regex المرتبط (مع المجموعات المسماة): 

 * @ * (?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 وسيطتين: التوقيع (يعمل كمعرف) والمتغيرات الافتراضية. على سبيل المثال (صادر من مثال سودوكو): 

 %@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 في برنامج نصي بلغة 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

سوف يؤدي إلى بيثون: 

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

يتيح ذلك المزيد من المرونة والأتمتة عند إنشاء الوثائق الخاصة بك، حيث يمكن دمجها في نصوص بايثون الحالية وعمليات الأتمتة.

يحتوي الملف "test.py" على أمثلة لمعلمات مختلفة يمكن استخدامها.

مؤلف

جامعة بوتسدام | حلول بوتاسكو

يوسع
معلومات إضافية
تطبيقات ذات صلة
نوصي لك
أخبار ذات صلة الكل