https://github.com/sbtrn-devil/logipard

Flexible, language agnostic software documentation generator based on idea of collecting data from code base annotation comments into single machine-readable documentation model DB and using it as single point information source for generating variety of user-oriented documents
https://github.com/sbtrn-devil/logipard

documentation-generator documentation-tool javascript language-agnostic node-js

Last synced: 4 months ago
JSON representation

Flexible, language agnostic software documentation generator based on idea of collecting data from code base annotation comments into single machine-readable documentation model DB and using it as single point information source for generating variety of user-oriented documents

• Host: GitHub
• URL: https://github.com/sbtrn-devil/logipard
• Owner: sbtrn-devil
• License: isc
• Created: 2025-06-12T10:30:06.000Z (4 months ago)
• Default Branch: master
• Last Pushed: 2025-06-21T23:43:36.000Z (4 months ago)
• Last Synced: 2025-06-22T00:26:39.890Z (4 months ago)
• Topics: documentation-generator, documentation-tool, javascript, language-agnostic, node-js
• Language: JavaScript
• Homepage: https://sbtrn-devil.github.io/logipard/
• Size: 1.57 MB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README-ru.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Logipard: Инструмент и фреймворк для генерации документации к программному обеспечению #

Logipard -- это инструмент и фреймворк для генерации документации к программному обеспечению путем извлечения аннотаций из комментариев в исходном коде и других текстовых источников.

Он работает по сходному принципу с такими инструментами, как Doxygen, Javadoc, ROBODoc итд., но устраняет ряд недостатков, присущих существующим решениям.

- Readme-страницы: [EN](README.md), [RU](README-ru.md)

- Страницы с полной документацией: [EN](https://sbtrn-devil.github.io/logipard/index.html), [RU](https://sbtrn-devil.github.io/logipard/index-ru.html)

---

- Начало работы с Logipard[>>](#_AuFQCmFf-165)

  - Установка[>>](#_AuFQCmFf-167)

  - Пример для быстрого старта[>>](#_AuFQCmFf-170)

    - Основы документирования[>>](#_AuFQCmFf-173)

    - Советы по хорошему стилю[>>](#_AuFQCmFf-176)

    - Подготовка файла шаблона HTML[>>](#_AuFQCmFf-179)

    - Подготовка файла конфигурации LP[>>](#_AuFQCmFf-182)

    - Запуск конвейера LP[>>](#_AuFQCmFf-185)

    - Подготовка README-фрагмента[>>](#_AuFQCmFf-188)

    - Заключение[>>](#_AuFQCmFf-191)

---



# Начало работы с Logipard #

В этом разделе мы объясним, что такое Logipard, и с какой стороны за него браться.

## Мотивация

Существующие генераторы документации на основе аннотаций часто имеют проблемы с решением основных задач:

1. **Ограниченный охват документации**

Большинство инструментов генерируют документацию, ориентированную исключительно на объекты кода (например, классы, модули, функции). Однако в них нет удовлетворительной поддержки для документации

более высокого уровня, такой как:

    - Отдельные руководства по быстрому началу работы и типовые примеры использования.

   - Документация в терминах объектов и рабочих процессов, специфичных для предметной области, которые могут не иметь простого 1:1 соответствия с объектами кода.

   - Встроенные заметки разработчика, ссылки на задачи, произвольные метаданные, и прочие виды нестандартной информации.

2. **Ограничения, связанные с языками**

Эти инструменты обычно привязаны к конкретным языкам программирования, в связи с чем возникают трудности с документированием:

   - Объектов более высокого уровня или специфичных для предметной области (например, скриптов, ресурсов, вспомогательных инструментов).

   - Отношения объектов между различными предметными областями (например, между основным языком и скриптовой системы).

   Кроме того, обычно существуют ограничения на места размещения аннотаций, что ограничивает гибкость в организации и структурировании исходников документации.

3. **Жёсткий формат выходных данных**  

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

   - Связь или перекрёстные ссылки между разнородными артефактами документации.

   - Эффективное использование машиночитаемых форматов (например, XML, JSON), даже если инструмент способен их генерировать, т. к. они часто содержат ту же самую фиксированную жёсткую структуру, что и человекочитаемый вывод.

## Как эти проблемы решаются в Logipard

Logipard предлагает новый подход к созданию документации, основанный на двух ключевых концепциях:

1. **Модель документации свободной формы (Freeform Documentation Object Model, или FDOM)**

   Logipard собирает все фрагменты документации в единую, в пределах проекта, базу данных, называемую **Модель документации свободной формы (FDOM)**. FDOM спроектирована, имея в виду следующие свойства:

   - **Гибкость**: Не накладывается никаких органичений на структуру документации или семантику элементов документа, позволяя включать в качестве таковых объекты программы, главы руководства пользователя,

   заметки разработчика, что-либо ещё, или всё вышеперечисленное в любой комбинации, и организовывать их в любую структуру, которую вы видите наиболее подходящей.

   - **Независимость от языка**: Поддержка документации из разнообразных источников, не привязанных к конкретной предметной области или языку программирования.

   - **Возможность перекрёстных ссылок**: FDOM предоставляет унифицированное пространство имён, позволяя легко делать перекрёстные ссылки между различными частями документации (например, между полем в SQL для создания таблицы

   и объектами, соответствующими ему в коде бизнес-логики).

   2. **Артефакт, ориентированный на инструменты**

   FDOM - машиночитаемый артефакт, ориентированный на инструменты, а не на конечного пользователя. Он служит первичным источником информации по документации, которую можно запрашивать и фрагментировать

   различными способами. Конкретная документация для конечного пользователя (например, справка по API, руководства пользователя) создаётся **генераторами** - вспомогательными инструментами, которые читают

   из FDOM соответствующие срезы информации, организуют их соответственно структуре целевого документа и выдают окончательный результат.

## Основные преимущества Logipard

- **Унифицированное хранение данных документации**: FDOM собирает все фрагменты документации в единую гибкую модель.

- **Независимость от языка и предметной области**: Документируйте элементы кода, скрипты, рабочие процессы, и прочие разнородные объекты, в одном общем пространстве.

- **Улучшенная перекрёстная ссылаемость**: Проще указывать связи между объектами из разных предметных областей или разных видов документации.

- **Настраиваемый вывод**: Генерация артефактов документации, заточенных под конкретные различные цели (например, заметки разработчика, документация конечного пользователя).

Теперь давайте ознакомимся с процессом...



## Установка ##

Установите Node.js 13 или выше.

Далее, установите Logipard CLI или глобально:

```

# с gitverse

npm install -g git+https://gitverse.ru/mikle33/logipard

# или: с github

npm install -g git+https://github.com/sbtrn-devil/logipard

# или: с npm

# TODO

```

или локально в вашу текущую папку:

```

# с gitverse

npm install git+https://gitverse.ru/mikle33/logipard

# или: с github

npm install git+https://github.com/sbtrn-devil/logipard

# или: с npm

# TODO

```

После глобальной инсталляции, Logipard CLI можно запустить из любой текущей папки:

```

lp-cli [cmd line options]

```

После локальной инсталляции, Logipard CLI можно запустить из текущей папки:

_Linux_:

```

node_modules/.bin/lp-cli [cmd line options]

```

_Windows_:

```

node_modules\.bin\lp-cli [cmd line options]

```

Запустите lp-cli без опций или с опцией `-h` или `--help` для справки по опциям командной строки (их достаточно немного, спецификация основной части работы

предполагается через конфигурационный файл (или файлы)).

После инсталляции можно пройти `Пример для быстрого старта`[>>](#_AuFQCmFf-170) для получения общего представления, как оно всё делается.



## Пример для быстрого старта ##

Например, вы собираетесь написать инновационную библиотеку, которая совершит переворот в мире программирования.

Вы создали каталог, в котором будет находиться проект (обозначим её ``), и, возможно, даже создали в ней `package.json` (будем считать, что это библиотека для Node.js).

Также вы установили Logipard CLI, как написано в `Установка`[>>](#_AuFQCmFf-167); будем считать, что команда CLI - `lp-cli [options]` (если вы установили локально,

то внесите соответствующую поправку).

Создайте основную кодовую базу библиотеки:

Содзать файл: `/index.js`

```

module.exports.leftpad = function leftpad(str, len, padding = ' ') {

	str = str + '';

	if (str.length >= len) return str;

	padding = (padding = padding + '').length ? padding : ' ';

	while (padding.length + str.length < len) {

		padding = padding + padding;

	}

	return padding.substring(0, len - str.length) + str;

}

```

Теперь можно начать документировать наше добро.



### Основы документирования ###

Основной источник докумнетации - аннотации кода в исходниках. В нашем случае, мы можем добавить несколько их вот таким образом:

Редактировать файл: `/index.js`

```

//#LP functions/leftpad { <#./%title: leftpad(str, len[, padding])#>

// Pad a string from left to the given minimum length with whitespaces or a given padding string.

//#LP ./str %arg: String to be padded

//#LP ./len %arg: Number, minimum required length of the padded string (<#ref leftpad/str#>)

//#LP ./padding %arg: String, optional. If specified, this string or its portion will be used for the padding instead of spaces.

//

// The string is repeated as required if it is less than the length required for the padding, and its leftmost part of the required length is used.

module.exports.leftpad = function leftpad(str, len, padding = ' ') {

	... // almost everything within can be left as is so far

	//#LP ./%return: The padded string with minimum length of (<#ref leftpad/len#>)

	return padding.substring(0, len - str.length) + str;

}

//#LP }

```

Аннотации в основном выглядят читабельно и, возможно, почти самоописательно (не считая некоторых характерных деталей синтаксиса, на которых мы не будем останавливаться прямо сейчас), но есть кое-что не очевидное на глаз,

о чём следует упомянуть.

Во-первых, техническое замечание: Logipard распознаёт в качестве аннотаций последовательности идущих подряд однострочных комментариев (здесь - `//`), возможно с некоторым кодом перед ними в начале строки, причём первый комментарий

начинается с токена `#LP`, и до ближайшей строки, которая не заканчивается однострочным комментарием. В нашем случае, `//` после `./padding` нужна для того, чтобы комментарий `// The string is ...` был включён в последовательность.

С другой стороны, линия с комментарием `// almost everything ...` отделена от последовательности линией без комментария, так что это "просто комментарий в коде", который не принимается во внимание.

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

Во-вторых, Logipard не имеет совершенно никакого представления об исходном коде и каких-либо сущностях, характерных для данного языка. Всё, что имеет значение - структура модели документации,

а определение этой структуры и аккуратное следование ей полностью зависит от вас.

Например, в нашей документации мы задали наличие следующих элементов со следующими именами:

- `functions`: элемент автоматически введён в модель в силу того, что мы задали его члены-подэлементы, будем считать его контейнером для списка функций

- `functions/leftpad`: основной элемент документации для нашей функции, содержит всё, что к ней относится (т. е. следующие элементы)

- `functions/leftpad/%title` (идёт от `./%title`): элемент, содержащий человекочитаемый заголовок для главного элемента

- `functions/leftpad/str`, `functions/leftpad/len`, `functions/leftpad/padding`: элементы, документирующие аргументы функции; заметьте, что каждый из них помечен тегом модели `%arg`

- `functions/leftpad/%return`: элемент, документирующий возвращаемое значение нашей функции

- `%arg`: тег модели с вот таким именем, введён в модель в силу того, что мы его использовали

Обратите внимание, что все семантические значения элементов (контейнер списка функций, главный элемент для функции, элементы для читаемого заголовка функции и возвращаемого значения, тот факт, что мы помечаем аргументы именно тегом `%arg`,

тот факт, что документируемая сущность - именно функция) сугубо конвенциональны, как и их имена. С точки зрения модели документации Logipard, они все - просто элементы общего вида, и на данном этапе их интерпретация

в тех качествах, которые описаны выше, пока что существует исключительно умозрительно.

Вы можете принимать другие конвенции для ваших собственных задач, но в рамках нашего быстрого старта будем придерживаться вот такой.

Ещё один момент - места расположения аннотаций на самом деле не имеют значения, размещайте их так, как вам удобнее. В данном случае мы разместили их рядом с декларацией функции, аналогично тому, как делается

в традиционных генераторах документации типа Javadoc, TSDoc, Doxygen, и т. п. (Но даже и здесь, мы решили разместить фрагмент `%return` рядом с оператором возврата, а не в одном блоке с описаниями параметров -

опять-таки, исключительно для примера, можно было разместить его и более традиционно.) Но в общем случае их можно разместить в любом месте файла с исходным кодом, или в другом файле, или даже разместить различные

подэлементы в совершенно разных местах. Это, возможно, не очень полезно для вещей вроде аргументов функции и её возвращаемого значения, но информация, имеющая отношение к функции и желательная к размещению

в её информационном узле, может не ограничиваться только этими данными.



### Советы по хорошему стилю ###

Хотя в модели документа нет встроенных ограничений на выбор структуры и имён для элементов, есть несколько моментов, которые желательно иметь в виду для поддержания хорошего стиля и сопровождаемости.

- краткие имена для элементов, которые предполагаются в качестве вспомогательных полей данных или для использования в качестве тегов, следует начинать с `%`. По удачному стечению обстоятельств, мы уже

так и сделали.

- элементы документации, специфичные для вашего проекта/модуля/библиотеки, следует размещать под одним общим корневым элементом с достаточно уникальным именем, характерным для данного проекта (__домен проекта__).

Это поможет избежать конфликта имён, когда дело коснётся интеграции нескольких проектов, и облегчит объединение их документации.

В нашем случае, мы выбрали для наших элементов не самые лучшие имена. Лучше было бы что-нибудь наподобие:

- `domain.our-unique.leftpad.for-nodejs/functions`

- `domain.our-unique.leftpad.for-nodejs/functions/leftpad`

- `domain.our-unique.leftpad.for-nodejs/functions/leftpad/%title`

- `domain.our-unique.leftpad.for-nodejs/functions/leftpad/str`

- `domain.our-unique.leftpad.for-nodejs/functions/leftpad/len`

- `domain.our-unique.leftpad.for-nodejs/functions/leftpad/padding`

- `domain.our-unique.leftpad.for-nodejs/functions/leftpad/%return`

- `%arg` (это, по определённым причинам, можно оставить как есть)

Допечатывать доменный префикс к именам элементов всякий раз, когда потребуется, разумеется, непрактично (даже при том, что требуется это не слишком часто). Для этого лучше определить алиас. Сделаем это:

Редактировать файл: `/index.js`

```

//#LP-alias M: domain.our-unique.leftpad.for-nodejs

// теперь вместо domain.our-unique.leftpad.for-nodejs/functions/... можно использовать M/functions

//#LP M/functions/leftpad { <#./%title: leftpad(str, len[, padding])#>

...

// ...остальная часть файла может быть оставлена без изменений, в ней используются относительные имена

```

Более того, этот `//#LP-alias M: domain.our-unique.leftpad.for-nodejs`, скорее всего, будет общей частью для всех файлов, содержащих документацию по нашему проекту, и к этой общей части, возможно,

со временем добавятся ещё некоторые. В целях дальнейшего уменьшения дубликации, можно вынести данный фрагмент в отдельный файл и просто подключать его везде, где нужно...

Создать файл: `/leftpad-module-inc.lp-txt`

```

#LP-alias M: domain.our-unique.leftpad.for-nodejs

```

(Обратите внимание, что у этого файла немного другая структура. Поскольку Logipard не имеет представления об языке программирования, можно использовать даже отдельные текстовые файлы, полностью состоящие из

аннотаций Logipard.)

Редактировать файл: `/index.js`

```

//#LP-include leftpad-module-inc.lp-txt

//#LP M/functions/leftpad { <#./%title: leftpad(str, len[, padding])#>

...

// ...остальная часть файла всё ещё остаётся без изменений

```



### Подготовка файла шаблона HTML ###

В этом быстром старте мы делаем HTML-документацию, и первое, что нам для этого потребуется - подготовить файл шаблона HTML.

Создать файл: `/leftpad-doc-html.tpl.html`

```

body {

	font-family: sans-serif;

}

code {

	font-family: monospace;

	background: lightgray;

	margin: 0;

	padding: 0;

}

pre {

	font-family: monospace;

	background: lightgray;

	margin: 0;

	padding: 0;

}

table, th, td { border: 1px solid; border-spacing: 0; border-collapse: collapse; }

table { margin: 0.5em }

CSS_TARGET





leftpad for node.js

1.0.0





HTML_TARGET





```

Данный шаблон - исключительно для примера, он включает самый необходимый минимум того, что возможно. Обратите внимание на метки `CSS_TARGET` и `HTML_TARGET`.



### Подготовка файла конфигурации LP ###

Теперь, чтобы перейти к чему-то более существенному, нам нужно подготовить конфигурационный файл Logipard. Мы не будем сейчас объяснять всю магию, происходящую здесь,

просто имейте в виду, что именно здесь вы реализуете свои конвенции по модели документа и указываете другие технические вещи.

Создать файл: `/lp-config.json`

```

//#charset utf-8

// (Этот комментарий выше будет принят во внимание; предполагается, что вы сохраняете данный файл в UTF-8)

// Заметим, что это не очень похоже на корректный JSON (взять хотя бы комментарии), но пока не обращайте на это внимание,

// просто скопируйте и перенесите в файл всё как есть.

{

	"+ config": {

	},

	"lp-extract": {

		"+ config": {

			// обратите внимание, что неабсолютные пути - относительно корня проекта (то есть, места, в котором вы сохраняете данный файл)

			"+ excludeInFiles": ["node_modules/**"]

		},

		"items": [

			{

				// секция для основной кодовой базы, в нашем случае это все JS-файлы

				"inFiles": ["**/*.js"], 

				"excludeInFiles": [],

				"outDir": "lp-extract.gen",

				"reader": "${LP_HOME}/lpxread-basic" $, // символ $ в конце - не опечатка!

				"lpxread-basic": {

					"srcType": "generic-c-like"

				}

			},

			{

				// помните leftpad-module-inc.lp-txt? он попадает под эту секцию

				"inFiles": ["**/*-inc.lp-txt"],

				"excludeInFiles": [],

				"forLPInclude": true,

				"outDir": "lp-extract.gen/lp-includes",

				"reader": "${LP_HOME}/lpxread-basic" $,

				"lpxread-basic": {

					"srcType": "lp-text"

				}

			}

		]

	},

	"lp-compile": {

		"+ config": {

		},

		"items": [

			{

				"inRootDir": "lp-extract.gen",

				"lpIncLookupDirName": "lp-includes",

				"writer": "${LP_HOME}/lpcwrite-basic-json" $,

				"lpcwrite-basic-json": {

					// можете настроить это под имя вашего проекта

					"outFile": "lp-compile.gen/leftpad-doc-fdom.json"

				}

			}

		]

	},

	"lp-generate": {

		"+ config": {

		},

		"items": [

			{

				"inFile": "lp-compile.gen/leftpad-doc-fdom.json", // здесь то же, что в outFile в секции lp-compile

				"writer": "${LP_HOME}/lpgwrite-example" $,

				"lpgwrite-example": {

					// тут очень много магии, просто скопируйте весь этот фрагмент

					"program": file("${LP_HOME}/lpgwrite-example-docprg.lpson" $, {

						"docprgPrologue": [ { "nameAlias": "M", "name": "domain.our-unique.leftpad.for-nodejs" } ],

						"docRootItems": {

							"query": [{ "with": "M/functions" }],

							"sort": { "byMember": "%order", "keyFormat": "ds-natural", "order": "asc" }

						},

						"LS_EXTENDS": "Extends (is a)",

						"LS_MEMBERS": "Members",

						"LS_NAME": "Name",

						"LS_DESCRIPTION": "Description",

						"LS_MEMBERS_FROM_EXTENTS": "Members from extents",

						"LS_ARGUMENTS": "Arguments",

						"LS_RETURNS": "Returns:",

						"LS_ERRORS": "Errors:",

						"LS_MEMBERS_DETAILED": "Members (detailed)",

						"LS_MEMBERS_FROM_EXTENTS_DETAILED": "Members from extents (detailed)",

						"LS_ARGUMENTS_DETAILED": "Arguments (detailed)",

						"LS_NOTES": "Notes",

						"LS_PROPERTIES": "Properties",

						"LS_PROPERTIES_FROM_EXTENTS": "Properties from extents",

						"LS_METHODS": "Methods",

						"LS_METHODS_FROM_EXTENTS": "Methods from extents"

					}),

					"renders": [

						{

							"docModel": "DocMain",

							"renderer": "${LP_HOME}/lpgwrite-example-render-html" $,

							"lpgwrite-example-render-html": {

								"outFile": "lp-generate.gen/leftpad-doc.html",

								"emitToc": true,

								"inTemplateFile": "leftpad-doc-html.tpl.html",

								"htmlPlaceholder": "HTML_TARGET",

								"cssPlaceholder": "CSS_TARGET",

								"localizedKeywords": {

									"SNAPBACK": "Snapback",

									"SNAPBACK_AND_SCROLL": "Snapback & Scroll",

									"ELEVATE": "Elevate",

									"RESET": "Reset",

									"ELEVATE_TO": "Elevate to...",

									"COPY_ITEM_NAME": "Copy this item's LP FDOM full name to clipboard:",

									"ITEM_UNFOLDED_ELSEWHERE": "Item unfolded elsewhere on page, click/tap to unfold here...",

									"MORE": "More... >>",

									"TABLE_OF_CONTENTS": "Table of contents"

								}

							}

						}

					]

				}

			}

		]

	}

}

```



### Запуск конвейера LP ###

Теперь мы готовы сгенерировать страницу документации для проекта нашего быстрого старта.

Предполагая, что текущий рабочий каталог - ``, и вы работаете под пользователем, имеющим право на запись в него, вызовите CLI:

```

lp-cli lp-config.json

```

Вы должны увидеть некоторый вывод, который, в случае успеха, выглядит примерно так:

```

=== Performing stage: EXTRACT ===

EXTRACT: 15.039ms

=== Performing stage: COMPILE ===

COMPILE: 18.592ms

=== Performing stage: GENERATE ===

Start render

lpgwrite-example-render-html: file lp-generate.gen/leftpad-doc.html created

GENERATE: 69.098ms

```

Должны появиться некоторые новые каталоги, в том числе `lp-generate.gen`, в котором должен находиться файл `leftpad-doc.html`. Это и есть наша страница с документацией, можно открыть её в браузере.

Неплохо для начала? Заметим ещё кое-что: это полностью самодостаточный HTML-файл, можно перемещать его как угодно, не боясь потерять зависимости, и ещё он статический и удобный для индексации поисковиками

при размещении в интернете.

Также загляните в каталог `lp-compile.gen` и файл `leftpad-doc-fdom.json` в нём. Это база данных модели вашей документации (в данном случае, в JSON-формате).

Хотя это выглядит не так интересно, и не очень человекочитаемо - это, вообще говоря, промежуточный артефакт, на который в большинстве случаев можно не обращать внимания - на самом деле, это ключевой элемент

в парадигме Logipard. Предполагается, что эта БД - единое место для хранения всех фрагментов LP-документации из проекта. В итоге может быть много конечных документов, составленных из разных

срезов этой БД, но для всех них она будет общим источником данных.

Продолжим наш быстрый старт и посмотрим, как это может работать в нашем случае.



### Подготовка README-фрагмента ###

Теперь, когда код нашей библиотеки завершён, хорошо бы добавить что-нибудь вроде README-файла. И, в идеале, сделать как отдельный README.md, так и добавить такую же информацию новой частью к основной HTML-странице.

Начнём с изготовления файла-исходника...

Создать файл: `/readme.lp-txt`

````

#LP-include leftpad-module-inc.lp-txt

#-LP обратите внимание на разный синтаксис, когда мы используем чисто-текстово-образные файлы

# кстати, фрагменты, начинающиеся со строки #-LP, считаются не аннотационными комментариями, и Logipard

# не включает их в БД и документмацию, они длятся до следующего разметочного тега #LP.

# То есть, вот этот параграф - всё ещё комментарий LP (решётки в начале на самом деле не нужны, но лучше соблюдать

# единообразие визуального стиля). Также обратите внимание, что согласованные отступы (т. е. одинаковое количество одного типа пробелов

# в начале каждой промежуточной линии в пределах #LP-фрагмента) учитываются и корректно обрабатываются.

#LP M/readme { <#./%title: leftpad: quickstart#>

String left pad, revised and improved.

#LP ./install { <#./%title: Install#> <#./%order: 1#>

```

$ npm install git+https:///leftpad

# TODO: actual location

```

#LP }

#LP ./usage { <#./%title: Usage#> <#./%order: 2#>

```

const { leftpad } = require('./leftpad');

leftpad('foo', 5);

// '  foo'

leftpad('foo', 2);

// 'foo'

leftpad('foo', 10, '+-=');

// '+-=+-=+foo'

```

#LP }

#-LP Кстати, не помешает добавить ссылку на инструкцию по использованию в раздел документируемой функции...

#LP M/functions/leftpad/usage { <#./%title: Usage#>

See some usage examples under <#ref readme/usage#>.

#LP }

#-LP И ещё добавим в секцию списка функций немного официального содержимого...

#LP M/functions: <#./%title: Functions reference#>

Reference on the library functions.

#-LP Тем не менее, имейте в виду один подводный камень при использовании многострочного #LP...: синтаксиса: рамки такого фрагмента ограничены следующим не-<#...#> #LP тегом или #-LP комментарием

# Поэтому строки после данного комментария снова находятся в M/readme (а сам комментарий, соответственно, заканчивается только на теге #LP)

#LP ./versions { <#./%title: Versions summary#> <#./%order: 3#>

#LP ./1.0.0: Initial release version.

#LP ./0.0.9: Pre-release version.

Was not documented with LP, so it pretty sucked.

#LP }

#LP }

````

Теперь добавим вот что...

Редактировать файл: `/lp-config.json`

```

...

	"lp-extract": {

	... // под "items"...

		"items": [

			// добавьте третий элемент (для учёта нового readme.lp-txt):

			...,

			{

				"inFiles": ["**/*.lp-txt"],

				"excludeInFiles": [],

				"outDir": "lp-extract.gen",

				"reader": "${LP_HOME}/lpxread-basic" $,

				"lpxread-basic": {

					"srcType": "lp-text"

				}

			}

		]

	},

...

	"lp-generate": {

	... // первый (и пока единственный) элемент под "items"...

		"items": [

			{

				"inFile": "lp-compile.gen/leftpad-doc-fdom.json",

				"writer": "${LP_HOME}/lpgwrite-example" $,

				"lpgwrite-example": {

... // в основном оставьте, как есть, кроме....

						"docRootItems": {

							"query": [{ "with": ["M/readme", "M/functions"] }], // <-- замените содержимое члена "query" на вот такое

							],

... // всё остальное остаётся как есть

						},

... // и здесь тоже

			},

			// далее, добавьте вот такой второй элемент в "items":

			{

				"inFile": "lp-compile.gen/leftpad-doc-fdom.json", // обратите внимание - всё ещё то же самое, что outFile в секции lp-compile

				"writer": "${LP_HOME}/lpgwrite-example" $,

				"lpgwrite-example": {

					"program": file("${LP_HOME}/lpgwrite-example-docprg.lpson" $, {

						"docprgPrologue": [ { "nameAlias": "M", "name": "domain.our-unique.leftpad.for-nodejs" } ],

						"docRootItems": {

							"query": [{ "with": ["M/readme"] }],

							],

							"sort": { "byMember": "%order", "keyFormat": "natural", "order": "asc" }

						}

					}),

					"renders": [

						{

							"docModel": "DocMain",

							"renderer": "${LP_HOME}/lpgwrite-example-render-md" $,

							"lpgwrite-example-render-md": {

								"outFile": "lp-generate.gen/leftpad-README.md",

								"emitToc": true,

								"addSourceRef": false,

								"header": "# leftpad #\n\n---",

							}

						}

					]

				}

			}

		// всё остальное остаётся как есть

		}

...

```

Снова запустите конвейер LP:

```

lp-cli lp-config.json

```

Теперь снова посмотрите в `lp-generate.gen`: должен появиться новый файл `leftpad-README.md` (посмотрите его каким-нибудь подручным MD-просмотрщиком), а файл `leftpad-doc.html` обновился -

теперь в нём есть та же информация, что и в readme, при этом осталась справка по функциям, и заметны прочие улучшения, о которых можно было догадаться при редактировании исходника readme.



### Заключение ###

Вот таким образом выполняются базовые документационные задачи Logipard; этого, возможно, более чем достаточно для повседневных нужд. Но в его рамках и с помощью модели документации можно сделать намного

больше, причём это могут быть даже задачи, выходящие за пределы обычного документирования. Для более подробного ознакомления с возможностями и более конкретного понимания, что мы сделали в быстром старте,

см. основную часть документации.

Также, в качестве примера более сложного проекта, документированного с помощью Logipard, можете ознакомиться с кодом самого Logipard. Все исходники документации намеренно оставлены в его пакете.

---

The page generated by Logipard 1.0.1 using lpgwrite-example + lpgwrite-example-render-md generator