Metadata-Version: 2.1
Name: d2doc
Version: 0.9.1
Summary: Make technical documentstion from data sets
Home-page: https://github.com/brobots-corporation/d2doc
Author: Evgenii Alaev
Author-email: ev.alaev@yandex.ru
License: GPL-3.0
Project-URL: Bug Reports, https://github.com/brobots-corporation/d2doc/issues
Project-URL: Source, https://github.com/brobots-corporation/d2doc
Description: 
        # d2doc
        Генерация документации на основании входных файлов с данными и шаблонов выходных документов
        
        [![Build Status](https://travis-ci.org/brobots-corporation/d2doc.svg?branch=master)](https://travis-ci.org/brobots-corporation/d2doc) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=d2doc&metric=alert_status)](https://sonarcloud.io/dashboard?id=d2doc)
        
        ## Возможности
        * Работа в ОС: `Linux`, `Mac OS X`, `Windows`;
        * Формат шаблонов [jinja2](https://jinja.palletsprojects.com/);
        * Формат файлов входных данных `xml,json,yaml,bsl`.
        * Статика
        
        ## Установка и обновление
        
        * Установить Python версии не ниже 3.6;
        * Установить пакет d2doc из PyPI командой:
            ```sh
            pip install d2doc
            ```
        * Для обновления пакета необходимо воспользоваться командой:
            ```sh
            pip install -U d2doc
            
        ## Использование скрипта
        ```
        Usage: d2doc.py [OPTIONS] COMMAND [ARGS]...
        
        Options:
          --log-level TEXT  Log level [CRITICAL, FATAL, ERROR, WARNING, DEBUG, INFO,
                            NOTSET]                 
          --help            Show this message and exit.
        
        Commands:
          build
        ```  
        Использование команды `build`
        ```
        Usage: d2doc.py build [OPTIONS]
        
        Options:
          -t, --templates PATH        Path to template files.
          -s, --start-templates TEXT  Root templates separated by comma.
          -f, --data-file FILE        Input data file (Global for all templates).
          -d, --data-dir PATH         Input data dir (Global for all templates).
          -m, --data-dir-mask TEXT    Files mask for option '--data-dir-mask'.
          -o, --output-dir PATH       Output dir for documentation.
          --erase-output-dir          Erase output dir befor build.
          --output-format TEXT        File extention for output files.
          --transliterate-urls        Transliterate urls.
          --static PATH               Dir with static files to copy in output (multiple).
          --help                      Show this message and exit.
        ```
        
        
        ### Пример использования скрипта в Linux
        ```sh
        d2doc.py build \
        	--templates './test/test1/templates' \
        	--start-templates 'Оглавление' \
        	--data-dir './test/test1/data' \
        	--data-dir-mask '**/*.json' \
        	--output-dir './test/test1/doc' \
          --static './test/test1/static' \
        	--erase-output-dir
        ```
        
        ### Пример использования скрипта в Linux c использованием переменных среды
        ```sh
        export D2DOC_BUILD_TEMPLATES='./test/test1/templates'
        export D2DOC_BUILD_START_TEMPLATES='Оглавление'
        export D2DOC_BUILD_DATA_DIR='./test/test1/data'
        export D2DOC_BUILD_DATA_DIR_MASK='**/*.json'
        export D2DOC_BUILD_OUTPUT_DIR='./test/test1/doc'
        export D2DOC_BUILD_STATIC='./test/test1/doc/static'
        export D2DOC_LOG_LEVEL='DEBUG'
        d2doc.py build --erase-output-dir
        ```
        
        ## Шаблоны
        Для рендера страниц используется движок `jinja2`
        
        ### Вспомогательные функции
        Функции для использования в шаблонах (плюсом к разнообразию функций [jinja2](https://jinja.palletsprojects.com/))
        
        #### tolist
        Используется для обработки коллекций из файлов xml в jinja2, когда возможен только один элемент в колекции. Если передан один объект, то возвращается список с этим объектом.
        
        ```
        tolist(obj_or_list)
        ```
        | Parameter | Requare|Description |
        | --- | --- | --- |
        | `obj_or_list` | Да | Список произвольных объектов или произвольный объект |
        
        Пример:
        ```
        {% set config_xml = from_file("./configuration.xml") %}
        {% set config_props = config_xml.MetaDataObject.Configuration.Properties %}
        {% for role in tolist(config_props.DefaultRoles['xr:Item']) %}
            * {{role['#text']}}\\
        {% endfor %}
        ```
        
        #### url
        Используется для построения внутренних ссылок.
        
        ```
        url(url,target_template,data, [other])
        ```
        | Parameter | Requare|Description |
        | --- | --- | --- |
        | `url` | Да | Шаблон ссылки в формате jinja2 |
        | `target_template` | Да | Имя файла шаблона, по которому должна генерироваться ссылка `url` |
        | `url` | Да | Данные для передачи в шаблон `target_template` |
        | `other` | Нет | Прочие параметры для рендера ссылки по шаблону `url` |
        
        Пример:
        ```
        [Справочник {{ name }}]({{ url(url = 'sprs/{{ name }}.md', target_template = 'spr.j2', data = spr, name='Users') }})
        
        Результат:
        [Справочник Users](sprs/Users.md) 
        ```
        
        #### from_file
        Получение данных из файла. Поддерживаемые форматы `xml,json,yaml,bsl` 
        
        ```
        from_file(file, format)
        ```
        
        | Parameter | Requare|Description | Default
        | --- | --- | --- | --- |
        | `file` | Да | Путь к файлу данных | |
        | `format` | Нет | Формат файла (`xml,json,yaml,bsl`) | Определяется по расширению файла |
        
        Пример:
        ```
        {% set s2 = from_file("./test/test1/data/s2.json") %}
        ...
        далее используем переменную s2
        ```
        
        #### from_dir
        Получение данных из каталога с файлами данных. Файлы данных объединяются в единый объект данных в памяти. Поддерживаниемые форматы `xml,json,yaml,bsl` 
        
        ```
        from_dir(path, mask)
        ```
        
        | Parameter | Requare|Description|
        | --- | --- | --- |
        | `path` | Да | Путь к каталогу с файлами данных |
        | `mask` | Да | Маска файлов (формат `glob`).|
        
        Пример:
        ```
        {% set s1 = from_dir("./test/test1/data", '**/*.json') %}
        {% set s2 = from_dir("./test/test1/data", '**/*') %}
        ...
        Далее используем переменную s1 и s2. 
        Имена вложенных каталогов и имена файлов встраиваются в выходную структуру. 
        Точка (.) в именах файлов (включая расширение файла) и каталогов заменяется на _
        ```
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: Russian
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.6.0
Description-Content-Type: text/markdown
