Изучите решения с открытым исходным кодом для написания технической документации с диаграммами.
Обзор
В предыдущей статье я описал текстовый подход для рисования различных видов диаграмм и их программного обслуживания. Давайте рассмотрим различные решения с открытым исходным кодом, которые можно использовать для написания технической документации, а также использование текстового подхода для построения диаграмм.
Есть несколько преимуществ использования текстового подхода для построения диаграмм.
- Управлять версиями очень просто. Разработчик может легко отслеживать изменения, внесенные в диаграммы. Диаграммы теперь рассматриваются как часть вашего исходного кода или репозитория документов.
- Используя библиотеки и инструменты с открытым исходным кодом для написания технической документации, а также библиотеку Javascript Mermaid для построения диаграмм и графиков, я могу легко создавать и предоставлять документацию.
- Стандартизация. Больше никаких диаграмм с разными стилями, и презентация всегда будет последовательной.
Emacs
Начнем с Emacs. Несмотря на то, что редактору уже почти 40 лет, Emacs по-прежнему остается одним из лучших и широко используемых редакторов, пользующихся большой поддержкой со стороны сообщества.
В предыдущей статье я показал вам, как писать и генерировать техническую документацию с помощью Emacs.
Используя пакеты Emacs mermaid-cli и ob-mermaid, я могу генерировать диаграммы и диаграммы в Emacs и связывать их с документацией.
Установите mermaid-cli глобально, используя npm.
npm i -g @mermaid-js/mermaid-cli
Установите пакет русалки Emacs.
(use-package ob-mermaid :custom (setq ob-mermaid-cli-path "/usr/bin/mmdc") )
Создайте схему русалки.
#+begin_src mermaid :file diagram.png
journey
title My working day
section Go to work
Make tea: 5: Me
Go upstairs: 3: Me
Do work: 1: Me, Cat
section Go home
Go downstairs: 5: Me
Sit down: 5: Me
#+end_src
Выполните блок кода, чтобы сгенерировать диаграмму.
Конфигурацию Emacs, которую я использовал, можно найти в этом репозитории.
Сфинкс
Давайте продолжим знакомство с Sphinx, генератором документации на основе Python.
Для начала установите и настройте Sphinx, используя руководство Начало работы, чтобы создать простой сайт со статической документацией.
Установите расширение русалки.
pip install sphinxcontrib-mermaid
В conf.py добавьте расширение.
extensions = ["sphinxcontrib.mermaid"]
Теперь я могу использовать директиву mermaid для создания диаграмм. Например. в любом первом файле.
.. mermaid::
sequenceDiagram
participant Alice
participant Bob
Alice->John: Hello John, how are you?
loop Healthcheck
John->John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail...
John-->Alice: Great!
John->Bob: How about you?
Bob-->John: Jolly good!
МКдокс
Для MkDocs следуйте руководству Начало работы, чтобы установить библиотеку и создать пример проекта.
Установите mkdocs-mermaid2-plugin.
pip install mkdocs-mermaid2-plugin
В mkdocs.yml добавьте плагины.
plugins: - search - mermaid2
Теперь я могу использовать директиву mermaid для создания диаграмм в любом файле Markdown. Например. в docs/index.md.
# Diagram
```mermaid
graph LR
A[Start] --> B{Error?};
B -->|Yes| C[Hmm...];
C --> D[Debug];
D --> B;
B ---->|No| E[Yay!];
```
Запустите mkdocs serve, чтобы увидеть сгенерированный сайт документации.
Примечание: mkdocs-material инсайдерская версия также предоставляет экспериментальное расширение для поддержки Mermaid.
Джекилл
Для Jekyll следуйте Краткому руководству, чтобы создать сайт.
Установите jekyll-spaceship, добавив следующую строку в файл Gemfile.
gem 'jekyll-spaceship'
Затем запустите bundle install.
Добавьте плагин в _config.yml.
plugins: - jekyll-feed - jekyll-spaceship
Теперь я могу создавать диаграммы в любом файле Markdown. Например. в index.markdown.
```mermaid!
sequenceDiagram
participant Alice
participant Bob
Alice->John: Hello John, how are you?
loop Healthcheck
John->John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail...
John-->Alice: Great!
John->Bob: How about you?
Bob-->John: Jolly good!
```
Запустите bundle exec jekyll serve, чтобы увидеть результат.
Хьюго
Для Hugo следуйте руководству Начало работы, чтобы установить и создать сайт.
Давайте установим тему hugo-theme-learn.
git submodule add https://github.com/matcornic/hugo-theme-learn.git themes/hugo-theme-learn
В config.toml измените тему.
baseURL = 'http://example.org/' languageCode = 'en-us' title = 'My New Hugo Site' theme = "hugo-theme-learn"
Теперь я могу создавать диаграммы в любом файле Markdown.
---
title: "My First Post"
date: 2021-10-19T15:40:22+08:00
draft: false
---
{{<mermaid align="left">}}
graph LR;
A[Hard edge] -->|Link text| B(Round edge)
B --> C{Decision}
C -->|One| D[Result one]
C -->|Two| E[Result two]
{{< /mermaid >}}
Запустите hugo server, чтобы увидеть результат.
Гэтсби
Для Gatsby следуйте руководству Быстрый старт, чтобы установить и создать сайт.
Добавьте поддержку страниц Markdown, следуя руководству здесь.
Добавьте плагин Mermaid, следуя руководству здесь.
npm install --save gatsby-remark-mermaid gatsby-transformer-remark puppeteerВаш gatsby-config.jsдолжен выглядеть так.
module.exports = {
siteMetadata: {
siteUrl: "https://www.yourdomain.tld",
title: "gatsby",
},
plugins: [
"gatsby-plugin-image",
"gatsby-plugin-sharp",
"gatsby-transformer-sharp",
{
resolve: "gatsby-source-filesystem",
options: {
name: "images",
path: "./src/images/",
},
__key: "images",
},
{
resolve: "gatsby-source-filesystem",
options: {
name: "pages",
path: `${__dirname}/src/markdown-pages`,
},
__key: "pages",
},
{
resolve: "gatsby-transformer-remark",
options: {
plugins: ["gatsby-remark-mermaid"],
},
},
],
};
Создайте файл Markdown в папке src/markdown-pages folder.
--- slug: "/page/my-first-page" date: "2021-10-19" title: "Page 1" --- # Diagram ```mermaid graph LR install[Install Plugin] install --> configure[Configure Plugin] configure --> draw[Draw Fancy Diagrams] ```
Запустите npm run develop, чтобы увидеть результаты.
Попробуйте тему Docz, чтобы создать веб-сайт с документацией.
Докузавр
Для Docusaurus следуйте руководству Начало работы, чтобы установить и настроить сайт.
Примечание. Если вы столкнулись с какой-либо ошибкой, вызывающей браузер, попробуйте BROWSER=none yarn start
Установите плагин mdx-mermaid.
yarn add mdx-mermaid mermaid
Обновите docusaurus.config.js, чтобы добавить плагин.
presets: [
[
"@docusaurus/preset-classic",
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
remarkPlugins: [require("mdx-mermaid")],
sidebarPath: require.resolve("./sidebars.js"),
......
],
Теперь я могу использовать директиву mermaid для создания диаграмм в любом файле Markdown.
Посмотрите также сравнение с другими инструментами. Довольно интересно.
Резюме
В этой статье я рассмотрел несколько библиотек с открытым исходным кодом, которые можно использовать для создания веб-сайтов со статической документацией. Ниже приведены дополнительные варианты, которые вы можете изучить самостоятельно.
- документировать
- VuePress и следующая версия vuepress-next
- Экстра
- "Пеликан"
- Гексо
Пример кода, который я использовал, можно найти в этом репозитории.
Если вы еще не являетесь участником Medium и хотите им стать, нажмите здесь. (Часть вашей абонентской платы будет использована для поддержки alpha2phi.)
Также ознакомьтесь с этими статьями!
