# Написание документации для модулей

## Краткое описание
Данный модуль разработан для создания справочной документации о системе CIEXT.  
Здесь представлены примеры добавления и настройки отображения документации в справочнике.

### Инструкция создания документации для модуля

1. #### Создание каталогов  
В корневой директории модуля создайте два каталога: config, docs.  
Пример пути к созданию каталогам:
```
my-module/config  //папка конфигураций модуля
my-module/docs    //папка с файлами документации
```
2. #### Создание конфигурационного файла  
a) Создание конфигурационного файла, для добавления документации о модуле в справочник.   
Создайте файл doc.php в каталоге ```my-module/config```.  
Если модуль уникальный, не расширяет возможности других модулей и для него нужно создать новую ветку - создайте файл со структурой:  
```
return[  
    'my-module-uniq-name' => [
        'label'    => 'Название модуля',
        'file'     => __DIR__ . '/../docs/description_file.md',
        'position' => 70,
        'acl_resource' => 'ресурс в системе',
        'acl_action'   => 'действие по которому выполняется проверка',
        'uri'      => 'resmng/index',
        'pages'    => [...],       
    ]
]
```
, где  
my-module-uniq-name - уникальний ключ который идентифицирует модуль в справочнике;  
label - заглавия документа;  
file - полный путь к файлу с описанием в формате .md;  
position - порядок отображения элемента в дереве справочника;  
acl_resource - модуль, в котором создано правило для проверки;
acl_action - правило, разрешающее использование модуля;
uri - метка для парсера, чтобы добавить возможность модулю ссылаться на свою документацию. *Важно! Шаблон создания модуль/метод*
pages - вложенные страницы с той же структурой. (Опционально) 
Пример:  
```
return[  
    'resmng_welcome' => [
        'label'    => 'Управление ресурсами CMS',
        'file'     => __DIR__ . '/../docs/welcome.md',
        'position' => 10,
        'pages'    => [
            'catalog'  => [
                'label'    => 'Каталог',
                'file'     => __DIR__ . '/../docs/welcome.md',
                'position' => 10,
            ],
            'tpl'      => [
                'label'    => 'Шаблон страницы',
                'file'     => __DIR__ . '/../docs/welcome.md',
                'position' => 20,
            ],
            'page'     => [
                'label'    => 'Страница',
                'file'     => __DIR__ . '/../docs/welcome.md',
                'position' => 30,
                'pages'    =>[
                    'resource' => [
                        'label'    => 'Ресурс',
                        'file'     => __DIR__ . '/../docs/welcome.md',
                        'position' => 10,
                    ]
                ]
            ],            
        ]
    ],
];
```  
б) Создание конфигурационного файла для модуля расширяющего возможности другого модуля.  
Создайте doc.php файл с структурой:  
```
return[
    'parent-module-key' => [
        'pages' => [
            'my-module-uniq-name' => [
                'label'    => 'Название модуля',
                'file'     => __DIR__ . '/../docs/description_file.md',
                'position' => 70,       
            ]
        ]
    ]
];
```  
,где pages - указывает на создание разветвления, существование вложенности  
Пример:  
```
return[
    'resmng_welcome' => [
        'pages' => [
            'page' => [
                'pages' => [
                    'resource' => [
                        'pages' => [
                            'filemng' => [
                                'label'    => 'Файл менеджер',
                                'file'     => __DIR__ . '/../docs/description_file.md',
                                'position' => 10,
                            ]
                        ]
                    ]
                ]
            ],
        ]
    ]
];
```   
3. #### Создание файла описания  
В каталоге ```my-module/docs/``` создайте файл description_file.md, где description_file - название файла.

4. #### Создание ссылки на ресурс ciext_help
Для этого в нужном месту вставте строку для парсера {{{doc_link_ід страницы в дереве}}}