Документация

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/docs/vp"
+    schedule:
+      interval: "daily"

.gitignore

@@ -1,3 +1,6 @@
 out/
 oscript_modules/
 *.ospx
+docs/vp/node_modules
+/docs/vp/.vitepress/dist
+/docs/vp/.vitepress/cache

README.md

@@ -1,3 +1,6 @@
+
+![cover CiqiQHG1](https://github.com/user-attachments/assets/f24d50a1-b006-407a-8e81-d737130e4f29)
+
 # Autumn/ОСень
 
 [![Тестирование](https://github.com/autumn-library/autumn/actions/workflows/testing.yml/badge.svg?branch=master)](https://github.com/autumn-library/autumn/actions/workflows/testing.yml)

docs/vp/.vitepress/config.mjs

@@ -0,0 +1,85 @@
+import { defineConfig } from 'vitepress'
+import hljs from 'highlight.js';
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+
+  appearance:'force-dark',
+  markdown: {
+    // https://github.com/markdown-it/markdown-it#syntax-highlighting
+    highlight(str, lang, attrs) {
+      if (lang && hljs.getLanguage(lang)) {
+        try {
+          return hljs.highlight(str, { language: lang }).value;
+        } catch {}
+      }
+
+      return '';
+    },
+  },
+
+  title: "Autumn Docs",
+  description: "Это документация для Autumn - DIF для OS",
+  lang: 'ru-RU',
+
+  locales: {
+    root: {
+      label: 'Русский',
+      lang: 'ru'
+    },
+
+  },
+
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+
+    logo: 'acorn-ol.png',
+
+    nav: [
+      { text: 'Главная', link: '/' },
+      { text: 'Документация', link: '/docs/Getting-started/About-autumn.md' }
+    ],
+
+    sidebar: [
+      {
+        text: 'Начало работы',
+        items: [
+          { text: 'Что такое Autumn?', link: '/docs/Getting-started/About-autumn.md' },
+          { text: 'Первое приложение', link: '/docs/Getting-started/First-steps.md' },
+          { text: 'Дополнительные пакеты Autumn', link: '/docs/Getting-started/Additional-packages.md' },
+        ]
+      },
+      {
+        text: 'Использование фреймворка',
+        items: [
+          { text: 'Объявление компонента', link: '/docs/Framework-elements/Component-declaration.md' },
+          { text: 'Получение экземпляра компонента', link: '/docs/Framework-elements/Component-instance.md' },
+          { text: 'Связывание компонентов между собой', link: '/docs/Framework-elements/Components-binding.md' },
+          { text: 'Фабрика компонентов', link: '/docs/Framework-elements/Components-factory.md' },
+          { text: 'Внедрение зависимостей в поля и функции-сеттеры', link: '/docs/Framework-elements/Dependency-injection.md' },
+          { text: 'Внедрение настроек приложения', link: '/docs/Framework-elements/App-settings-injection.md' },
+          { text: 'Генератор экземпляров компонентов', link: '/docs/Framework-elements/Instance-generator.md' },
+          { text: 'Произвольные аргументы конструктора', link: '/docs/Framework-elements/Custom-arguments.md' },
+          { text: 'Алиасы компонентов', link: '/docs/Framework-elements/Aliaces.md' },
+          { text: 'Упорядочивание компонентов при получении в виде сортированных коллекций', link: '/docs/Framework-elements/Components-sorting.md' },
+          { text: 'Приоритизация компонентов с общим алиасом', link: '/docs/Framework-elements/Components-prioritization.md' },
+          { text: 'Переопределение компонента по имени', link: '/docs/Framework-elements/Component-overriding.md' },
+          { text: 'Пост-инициализация компонента', link: '/docs/Framework-elements/Component-post-initialization.md' },
+          { text: 'Уникальность экземпляров компонентов', link: '/docs/Framework-elements/Component-uniqueness.md' },
+          { text: 'Дополнительная обработка компонента', link: '/docs/Framework-elements/Additional-processing.md' },
+          { text: 'Использование контекста приложения', link: '/docs/Framework-elements/App-context.md' },
+          { text: 'Условная регистрация компонентов в контексте приложения', link: '/docs/Framework-elements/Conditional-registration.md' },
+          { text: 'Инверсия управления запуском приложения', link: '/docs/Framework-elements/Launch-control-inversion.md' },
+          { text: 'Собственные аннотации', link: '/docs/Framework-elements/Custom-annotations.md' },
+          { text: 'Наследование аннотаций', link: '/docs/Framework-elements/Annotation-inheritance.md' },
+          { text: 'Обработка аннотаций', link: '/docs/Framework-elements/Annotations-processing.md' },
+          { text: 'Группировка компонентов по алиасу', link: '/docs/Framework-elements/Aliaces-grouping.md' },
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/autumn-library/autumn' }
+   ]
+  }
+})

docs/vp/.vitepress/theme/index.js

@@ -0,0 +1,19 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from 'vue'
+import DefaultTheme from 'vitepress/theme'
+import './style.css'
+
+/** @type {import('vitepress').Theme} */
+export default {
+  extends: DefaultTheme,
+  Layout: () => {
+
+
+    return h(DefaultTheme.Layout, null, {
+
+    })
+  },
+  enhanceApp({ app, router, siteData }) {
+
+  }
+}

docs/vp/.vitepress/theme/style.css

@@ -0,0 +1,146 @@
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/**
+ * Colors
+ *
+ * Each colors have exact same color scale system with 3 levels of solid
+ * colors with different brightness, and 1 soft color.
+ * 
+ * - `XXX-1`: The most solid color used mainly for colored text. It must
+ *   satisfy the contrast ratio against when used on top of `XXX-soft`.
+ *
+ * - `XXX-2`: The color used mainly for hover state of the button.
+ *
+ * - `XXX-3`: The color for solid background, such as bg color of the button.
+ *   It must satisfy the contrast ratio with pure white (#ffffff) text on
+ *   top of it.
+ *
+ * - `XXX-soft`: The color used for subtle background such as custom container
+ *   or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
+ *   on top of it.
+ *
+ *   The soft color must be semi transparent alpha channel. This is crucial
+ *   because it allows adding multiple "soft" colors on top of each other
+ *   to create a accent, such as when having inline code block inside
+ *   custom containers.
+ *
+ * - `default`: The color used purely for subtle indication without any
+ *   special meanings attched to it such as bg color for menu hover state.
+ *
+ * - `brand`: Used for primary brand colors, such as link text, button with
+ *   brand theme, etc.
+ *
+ * - `tip`: Used to indicate useful information. The default theme uses the
+ *   brand color for this by default.
+ *
+ * - `warning`: Used to indicate warning to the users. Used in custom
+ *   container, badges, etc.
+ *
+ * - `danger`: Used to show error, or dangerous message to the users. Used
+ *   in custom container, badges, etc.
+ * -------------------------------------------------------------------------- */
+
+ :root {
+  --vp-c-default-1: var(--vp-c-gray-1);
+  --vp-c-default-2: var(--vp-c-gray-2);
+  --vp-c-default-3: var(--vp-c-gray-3);
+  --vp-c-default-soft: var(--vp-c-gray-soft);
+
+  --vp-c-brand-1: var(--vp-c-indigo-1);
+  --vp-c-brand-2: var(--vp-c-indigo-2);
+  --vp-c-brand-3: var(--vp-c-indigo-3);
+  --vp-c-brand-soft: var(--vp-c-indigo-soft);
+
+  --vp-c-tip-1: var(--vp-c-brand-1);
+  --vp-c-tip-2: var(--vp-c-brand-2);
+  --vp-c-tip-3: var(--vp-c-brand-3);
+  --vp-c-tip-soft: var(--vp-c-brand-soft);
+
+  --vp-c-warning-1: var(--vp-c-yellow-1);
+  --vp-c-warning-2: var(--vp-c-yellow-2);
+  --vp-c-warning-3: var(--vp-c-yellow-3);
+  --vp-c-warning-soft: var(--vp-c-yellow-soft);
+
+  --vp-c-danger-1: var(--vp-c-red-1);
+  --vp-c-danger-2: var(--vp-c-red-2);
+  --vp-c-danger-3: var(--vp-c-red-3);
+  --vp-c-danger-soft: var(--vp-c-red-soft);
+}
+
+/**
+ * Component: Button
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-button-brand-border: transparent;
+  --vp-button-brand-text: var(--vp-c-white);
+  --vp-button-brand-bg: var(--vp-c-brand-3);
+  --vp-button-brand-hover-border: transparent;
+  --vp-button-brand-hover-text: var(--vp-c-white);
+  --vp-button-brand-hover-bg: var(--vp-c-brand-2);
+  --vp-button-brand-active-border: transparent;
+  --vp-button-brand-active-text: var(--vp-c-white);
+  --vp-button-brand-active-bg: var(--vp-c-brand-1);
+}
+
+/**
+ * Component: Home
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    120deg,
+    #F59D34 50%,
+    #E6673E
+  );
+
+  --vp-button-brand-bg: #CF6E3B;
+  --vp-button-brand-hover-bg: #AD5933;
+  --vp-c-brand-1: #CF6E3B;
+  --vp-c-bg: #141211;
+  --vp-c-bg-soft:#231A15;
+  --vp-sidebar-bg-color:#141211; 
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    #F59D34 50%,
+    #E6673E 50%
+  );
+  --vp-home-hero-image-filter: blur(44px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(68px);
+  }
+}
+
+/**
+ * Component: Custom Block
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-custom-block-tip-border: transparent;
+  --vp-custom-block-tip-text: var(--vp-c-text-1);
+  --vp-custom-block-tip-bg: var(--vp-c-brand-soft);
+  --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
+}
+
+/**
+ * Component: Algolia
+ * -------------------------------------------------------------------------- */
+
+.DocSearch {
+  --docsearch-primary-color: var(--vp-c-brand-1) !important;
+}
+
+

docs/vp/docs/Framework-elements/Additional-processing.md

@@ -0,0 +1,60 @@
+# Дополнительная обработка компонента
+
+Предположим, вы хотите сделать лошадку из желудей. Что для этого нужно? Для начала надо взять несколько желудей. Они будут немного отличаться друг от друга: тот, что покрупнее, пойдет на тело лошадки, тонкие желуди пойдут ноги, а вот этот смешной желудь в виде конуса будет мордой нашей лошадки. Конечно же, обмажем все пластилином, чтобы оно держалось вместе.
+
+Вы смотрите на получившуюся лошадку и понимаете: что-то не то. Желуди-то все блестящие, полированные! А вы так мечтали о теплой и матовой лошадке. Что же делать? Есть решение: желуди нужно обработать напильником, чтобы придать им приятный матовый оттенок.
+
+Конечно же вы можете добавить нужный код по приведению желудя к матовому цвету, например, в `ПриСозданииОбъекта`. Но желуди-то разные, копипастить код между разными компонентами... Как-то фу. Хорошо, что "ОСень" может нам помочь.
+
+Для дополнительной обработки объекта помимо "желудей" и "дубов" можно использовать `&Напильник`. Это специальный объект с методом `ОбработатьЖелудь`, который будет вызываться при каждом создании нового желудя.
+
+```1c
+// file: Классы/ПриданиеМатовогоЦветаЖелудям.os
+
+Функция ОбработатьЖелудь(Желудь, ОпределениеЖелудя) Экспорт
+    ВжухнутьРазочек(Желудь);
+
+    Возврат Желудь;
+КонецФункции
+
+&Напильник
+&Порядок(10)
+Процедура ПриСозданииОбъекта()
+КонецПроцедуры
+```
+
+Метод обработки напильником возвращает желудь, причем не обязательно возвращать *тот же самый* желудь. Вам может захотеться обернуть его в объект-контейнер и накинуть на него несколько новых методов, например, с помощью [decorator](https://github.com/nixel2007/decorator).
+
+Не каждый напильник стоит применять ко всем желудям. Вспоминая замечательный пример с панками, мы можем захотеть добавить напильник для полировки заклепок на напульсниках наших музыкантов. При этом очевидно, что далеко не все носят напульсники, да еще и с заклепками. В задаче ограничения применения напильника поможет повторяемый параметр аннотации `&Напильник` под названием `ПрименяетсяТолькоНа`. В нем можно указать имена или прозвища желудей, к которым применяется данный напильник.
+
+```1c
+// file: Классы/ПолировщикЗаклепок.os
+
+&Напильник(ПрименяетсяТолькоНа = "Панк")
+Процедура ПриСозданииОбъекта()
+
+КонецПроцедуры
+```
+
+С другой стороны сам желудь может захотеть ограничить список напильников, которые могут по нему вжухнуть. Или даже вовсе отключить вжухание всех напильников. Для этого на желудь можно навесить аннотацию `&ОсобоеОбращение`, которая может принимать булев параметр `ОтключитьВсеНапильники`, повторяемый строковый параметр `ПрименятьТолькоНапильник` и опять же повторяемый строковый параметр `НеПрименятьНапильник`. Назначение первого параметра, надеемся, достаточно очевидно, поэтому вот пример работы с одним из других:
+
+```1c
+// file: Классы/ПозерВНапульсниках.os
+
+&Желудь
+&ОсобоеОбращение(
+	ПрименятьТолькоНапильник = "ПолировщикЗаклепок"
+)
+Процедура ПриСозданииОбъекта()
+КонецПроцедуры
+```
+
+Зачем все это может быть нужно? Перфоманса ради, например. В случае большого количества компанейских желудей, которые не нуждаются в обработке напильником, можно отключить работу всех напильников для них. Ведь зачем тратить время на обработку, если она не нужна? При этом можно сохранить все плюшки от внедрения зависимостей и деталек через конструктор. Удобненько.
+
+Напильник в этой удивительной осенней вселенной тоже является желудем, поэтому может иметь зависимости от других желудей. Но тут надо аккуратно - можно окончательно упороться и улететь таки на дно циклических зависимостей.
+
+> Чтобы уберечь себя ото дна, все напильники инициализируются перед запуском приложения. Как в жизни - сначала разложил рядом инструменты, а потом начинаешь творить.
+
+"ОСень" в своем составе уже содержит два напильника: один отвечает за внедрение желудей в поля и методы установки значений, а второй - за вызовы методов `&ФинальныйШтрих`.
+
+Любой порядок стремится к хаосу, а несколько напильников - к порядку. Чтобы не запутаться, кто в какой последовательности вжухает по желудю каждому `Напильнику` в аннотации `&Порядок` можно/нужно задать порядок исполнения. Напильник внедрения зависимостей имеет порядок `0`, а напильник "Финального штриха" - `999999`. Вы вольны занять любое значение порядка между этими границами.