MkDocs

Один из моих проектом связан с написание Web-APIна базе REST. Естественно потребовалось вести документацию к API, для пользователей, для программистов из своего и других отделов, которые использовали его в своих проектах.

Изначально использовал DocBook, при помощи xsl процессора преобразовал все это в html и поставлял рядом с API. Пример использования можно посмотреть в Использование DocBook для написания документации. Одним из великолепных примеров многим известная книга SVN Book

Все вроде бы хорошо, кроме кастомизации(хотел подсветку кода), и сам формат XML избыточен и через какое-то время захотелось что-то вроде документации в Markdown который встроен в GitHub, GitLab.

Таким решением стал MkDocs. Перепечатывать пример со страницы проекта не вижу смысла, т. к. все довольно просто.

MkDocs уже имеет в себе минимальную версию prettify, для подсветки кода. Если этого не хватает, то собираем pretify, кидаем js файлы в docs/js и используем расширение «` с параметром.

<br />
```perl<br />
use v5.10.0;<br />
say &quot;Hello World&quot;;<br />
```<br />
```pascal<br />
Program HelloWord;</p>
<p>begin<br />
	 writeLn ('Hello World!')<br />
end.<br />
```<br />
```golang<br />
package main</p>
<p>import &quot;fmt&quot;</p>
<p>func main() {<br />
    fmt.Println(&quot;hello world&quot;)<br />
}</p>
<p>```<br />
```python<br />
print(&quot;Hello, World!&quot;)<br />
```;<br />
Реклама