Size: a a a

DocOps-сообщество

2019 August 26

B

Borodalo in DocOps-сообщество
@Nick_Volynkin - спасиб

Первый вариант выглядит интереснее второго.
Есть рекомендации на какие генераторы посмотреть?
источник

NV

Nick Volynkin in DocOps-сообщество
Borodalo
Доброго дня.

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

Допустим: общий документ описывающий проект.
Разработчики не видят блоков с информацией, которые видны администраторам.
Администраторы не видят блоков с информацией необходимых разработчикам


Или нужно пилить самому?
А расскажите чуть подробнее про задачу? Почему вы хотите скрыть блоки? Чтобы обратить внимание на важное и скрыть неважное? Чтобы не показывать критическую инфу вроде паролей от прода?
источник

B

Borodalo in DocOps-сообщество
Дока описывает проект

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

NV

Nick Volynkin in DocOps-сообщество
И ещё:
— кто будет писать документацию
— какие языки программирования знает разработчик, который будет всё это внедрять
источник

B

Borodalo in DocOps-сообщество
Nick Volynkin
И ещё:
— кто будет писать документацию
— какие языки программирования знает разработчик, который будет всё это внедрять
- Основу и большую часть кто-то из админов кому это интересно и лучше получается.
- python, go
источник

B

Borodalo in DocOps-сообщество
Пока не придумал как быть с информацией, которая будет прилетать в доку от разработчиков.

На данном этапе у них нет возможности писать в доку
источник

DE

Daniel Ershov in DocOps-сообщество
в сфинксе директива only
источник

DE

Daniel Ershov in DocOps-сообщество
она работает как с билдерами, так и с дополнительными тегами
источник

NK

ID:0 in DocOps-сообщество
Потратил час на то чтобы надёжно добавить CSS в проект на Sphinx. Придумал новую игру «код-конфиг-шаблон»:

— переменная конфига html_css_files бьёт редактирование шаблона layout.html в теме;
— вызов функции app.add_stylesheet  бьёт переменную конфига;
— редактирование шаблона бьёт вызов функции.
источник

DE

Daniel Ershov in DocOps-сообщество
Можно же замкнуть! Если выставить везде разные стили, какие в итоге победят?
источник

NV

Nick Volynkin in DocOps-сообщество
Daniel Ershov
Можно же замкнуть! Если выставить везде разные стили, какие в итоге победят?
Тогда в HTML <head> будет подключено две или три файла CSS.  От порядка подключения зависит, кто кого победит.
источник

FM

Fox Mulder in DocOps-сообщество
Nick Volynkin
Тогда в HTML <head> будет подключено две или три файла CSS.  От порядка подключения зависит, кто кого победит.
А разве это работает? Нет же такого свойства в html или я не в теме?
источник

SR

Stas Rychkov in DocOps-сообщество
Fox Mulder
А разве это работает? Нет же такого свойства в html или я не в теме?
В порядке приоритета http://www.htmlhelp.com/reference/css/style-html.html
источник

FM

Fox Mulder in DocOps-сообщество
Спасибо
источник

NK

ID:0 in DocOps-сообщество
Календарь конференций про документацию и технические коммуникации: https://keycontent.org/Calendar

За ссылку спасибо @SashP84
источник

NP

Nikolaj Potashnikov in DocOps-сообщество
Borodalo
спасиб
В asciidoc также довольно удобное профилирование
источник

B

Borodalo in DocOps-сообщество
Nikolaj Potashnikov
В asciidoc также довольно удобное профилирование
👍
источник
2019 August 27

СФ

Семён Факторович in DocOps-сообщество
источник

KE

Kirill Ermolenko in DocOps-сообщество
Доброе утро! Прошу помощи у сообщества экспертов. Есть набор микросервисов с синхронным взаимодействием по REST и асинхронным взаимодействием через шину сообщений. Хочется достичь следующего -что бы был некий портал с каталогом микросервисом, что бы при деплое автоматически обновлялась описание мс (что-то похожее на технический дизайн, структура всех сообщений и зависимости от других мс). Нет ли каких-то готовых инструментов для этих целей?
источник

NK

ID:0 in DocOps-сообщество
​​Introducing Markdown and Pandoc.
В этом месяце вышла новая книга про документацию как код: «Introducing Markdown and Pandoc: Using Markup Language and Document Converter», автор Thomas Mailund.

Если что, Markdown — это самый популярный (хотя не самый мощный) формат разметки, а Pandoc — универсальный конвертер между десятками форматов документов.

Книга начинает с основ Markdown и доходит до использования шаблонов и фильтров (препроцессоров) в Pandoc. Меня особенно порадовала глава про фильтры с примерами кода на Python и panflute. Когда-то я пытался писать фильтры для Pandoc, но не осилил, пришлось обрабатывать уже готовый HTML. Теперь сделаю ещё одну попытку.

Книгу можно купить на сайте издательства. Приятного чтения!
источник