Using MkDocs

1. Создание отдельного репозитория для документации¶

Шаг 1: Создайте новый репозиторий на GitLab или GitHub¶

Назовите его, например, project-docs (замените на имя вашего проекта).

Шаг 2: Инициализация документации¶

После создания репозитория инициализируйте в нём документацию с помощью выбранного инструмента:

Вариант 1: MkDocs¶

Установите MkDocs:
```
pip install mkdocs
```
Инициализируйте структуру документации:
```
mkdocs new project-docs
cd project-docs
```
Эта команда создаст базовую структуру, включая файл конфигурации mkdocs.yml и папку docs/ для хранения файлов с документацией.

Пример файла mkdocs.yml:

site_name: My Project Documentation
theme:
  name: mkdocs
nav:
  - Home: index.md
  - Getting Started: getting_started.md

Теперь можно начать добавлять документацию в файлы .md, расположенные в папке docs.

Вариант 2: Sphinx¶

Установите Sphinx:
```
pip install sphinx
```
Инициализируйте Sphinx:
```
sphinx-quickstart
```

Эта команда создаст структуру проекта с файлами конфигурации (conf.py) и папкой для хранения документации (например, в формате reStructuredText .rst).

Вариант 3: Docusaurus¶

Если вы хотите использовать Docusaurus, вам нужно Node.js.

Установите Docusaurus:

npx create-docusaurus@latest project-docs classic
cd project-docs

Начните редактировать документацию, добавляя файлы в папку docs/.

2. Хранение всей документации в одном репозитории¶

Шаг 1: Организация разделов документации¶

Если у вас есть несколько проектов, можно организовать разделы внутри документации для каждого проекта. Например:

project-docs/
├── docs/
│   ├── project1/
│   │   ├── index.md
│   │   └── usage.md
│   ├── project2/
│   │   ├── index.md
│   │   └── config.md
│   └── index.md
└── mkdocs.yml (или конфигурация Sphinx/Docusaurus)

В MkDocs в файле mkdocs.yml это можно настроить следующим образом:

site_name: My Projects Documentation
nav:
  - Project 1:
      - Overview: project1/index.md
      - Usage: project1/usage.md
  - Project 2:
      - Overview: project2/index.md
      - Configuration: project2/config.md

Для Sphinx можно настроить конфигурацию в файле conf.py, используя директивы для навигации по разным проектам, а для Docusaurus добавлять документацию для каждого проекта в отдельные разделы.

3. Автоматическая генерация и публикация документации¶

GitLab Pages:¶

Настройка .gitlab-ci.yml:

Если вы используете GitLab, создайте .gitlab-ci.yml для автоматической генерации и публикации документации на GitLab Pages:

image: python:3.8

pages:
  script:
    - pip install mkdocs
    - mkdocs build --clean
  artifacts:
    paths:
      - public
  only:
    - main

Этот файл скажет GitLab собирать сайт каждый раз, когда в ветке main будут изменения. Документация будет доступна по адресу https://yourusername.gitlab.io/project-docs.

GitHub Pages:¶

Публикация через GitHub Pages:

Для GitHub Pages можно настроить деплой через GitHub Actions.

Пример .github/workflows/gh-pages.yml для MkDocs:

name: Deploy MkDocs site to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.x'
      - name: Install MkDocs and dependencies
        run: |
          pip install mkdocs
      - name: Deploy to GitHub Pages
        run: |
          mkdocs gh-deploy --force

После этого GitHub автоматически соберет и опубликует сайт на GitHub Pages.

4. Поддержка версионирования документации¶

Если вам нужно поддерживать несколько версий документации (например, для разных релизов вашего проекта), то GitLab/GitHub Pages поддерживают эту функциональность:

GitLab/GitHub Pages можно настроить через различные ветки в репозитории.