diff --git a/README.md b/README.md index 97fffe0..deca0bc 100644 --- a/README.md +++ b/README.md @@ -24,9 +24,11 @@ - [С чего начать разработку open-source библиотеки](/tutorials/quick_guide.md); - [Зеркалирование GitHub -> GitLab](/tutorials/mirror_repo_to_gitlab.md); - [Мультиязычные README](/tutorials/create_multilang_readme_files.md); -- [Создание документации](/tutorials/documentation.md); +- [Создание документации (mkdocs)](/tutorials/documentation_mkdocs.md); +- [Создание документации (rtd)](/tutorials/documentation_rtd); - [Настройка ботов для репозитория](/tutorials/setup_bots.md); -- [Работа с Git](/tutorials/git_flow.md). +- [Работа с Git](/tutorials/git_flow.md); +- [Автоформатирование кода (black)](/tutorials/black_autoformatting.md). ### [Шаблоны](/templates) diff --git a/README_en.md b/README_en.md index e690fa0..05c9d05 100644 --- a/README_en.md +++ b/README_en.md @@ -24,7 +24,7 @@ All materials are available under the BSD-3 license. - [Getting started with open-source library development](/tutorials/quick_guide.md); - [Mirroring GitHub -> GitLab](/tutorials/mirror_repo_to_gitlab.md); - [Multilingual READMEs](/tutorials/create_multilang_readme_files.md); -- [Creating documentation](/tutorials/documentation.md); +- [Creating documentation](/tutorials/documentation_rtd); - [Setting up bots for the repository](/tutorials/setup_bots.md); - [Working with Git](/tutorials/git_flow.md). diff --git a/tutorials/black_autoformatting.md b/tutorials/black_autoformatting.md new file mode 100644 index 0000000..1417646 --- /dev/null +++ b/tutorials/black_autoformatting.md @@ -0,0 +1,41 @@ +# Автоформатирование кода в репозитории с помощью Black + +> [!TIP] +> Black — это инструмент для автоматического форматирования кода на Python. Он позволяет сделать код более читаемым и улучшить его структуру. + +Автоформатирование кода избавляет от рутинного процесса ручного выравнивания кода и позволяет сосредоточиться на более важных задачах. Black — один из самых популярных инструментов для автоформатирования кода на Python. + +Для локального использования Black необходимо установить его с помощью менеджера пакетов pip: + +```bash +pip install black +``` + +Или для поддержки форматирования Jupyter-ноутбуков: + +```bash +pip install "black[jupyter]" +``` + +После установки Black можно использовать его для форматирования кода в файлах и директориях. Например, чтобы отформатировать файл `example.py`, необходимо выполнить команду: + +```bash +black example.py +black my_project/ +``` + +Для репозиториев на GitHub можно использовать GitHub Actions для автоматического форматирования кода при создании Pull Request. Для этого необходимо добавить следующий workflow в файл `.github/workflows/black.yml`: + +```yaml +name: black-action +on: [push, pull_request] +jobs: + linter_name: + name: Run black formatter + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: rickstaa/action-black@v1.3.3 + with: + black_args: "." +``` diff --git a/tutorials/documentation_mkdocs.md b/tutorials/documentation_mkdocs.md new file mode 100644 index 0000000..f2bcf30 --- /dev/null +++ b/tutorials/documentation_mkdocs.md @@ -0,0 +1,189 @@ +# Руководство по документированию проекта - MkDocs Material + +## Введение +MkDocs - это статический генератор сайтов, предназначенный для создания документации. MkDocs Material - это тема для MkDocs, которая предоставляет множество возможностей для создания красивой и функциональной документации. +При создании документации документации mkdocs, документация хостится на GitHub Pages. Это позволяет не создавать дополнительных аккаунтов, быстрее и удобнее вносить изменения в документацию. + +## Установка и настройка +Для установки MkDocs Material необходимо выполнить следующцю команду: + +```bash +pip install mkdocs-material 'mkdocstrings[python]' +``` + +Для дальнейшей настройки необходимо создать файл конфигурации `mkdocs.yml` в корневой директории проекта. Пример файла конфигурации: + +```yaml +site_name: myproject +repo_name: myusername/myproject +repo_url: https://github.com/myusername/myproject +theme: + name: material + locale: en + features: + - announce.dismiss + - content.action.edit + - content.action.view + - content.code.annotate + - content.code.copy + - content.code.select + - content.footnote.tooltips + - content.tabs.link + - content.tooltips + - header.autohide + - navigation.expand + - navigation.footer + - navigation.indexes + - navigation.instant + - navigation.instant.prefetch + - navigation.instant.progress + - navigation.prune + - navigation.sections + - navigation.tabs + - navigation.tabs.sticky + - navigation.top + - navigation.tracking + - search.highlight + - search.share + - search.suggest + - toc.follow + - toc.integrate + palette: + - media: "(prefers-color-scheme)" + toggle: + icon: material/link + name: Switch to light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + accent: indigo + toggle: + icon: material/toggle-switch + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: black + accent: indigo + toggle: + icon: material/toggle-switch-off + name: Switch to system preference + font: + text: Roboto + code: Roboto Mono + +nav: + - Home: index.md + - Getting Started: user-guide/getting-started.md + - Installation: user-guide/installation.md + - API Reference: + - api-reference.md + - mymodule: mymodule.md + - mypackage: mypackage.md +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/myusername/myproject +plugins: + - search + - mkdocstrings +markdown_extensions: + - admonition + - codehilite + - footnotes + - meta + - toc: + permalink: True +``` + +Чтобы документация автоматически обновлялась на GitHub Pages, необходимо добавить в файл `.github/workflows/mkdocs.yml` следующий код: + +```yaml +name: mkdocs +on: + push: + branches: + - master + - main +permissions: + contents: write +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Configure Git Credentials + run: | + git config user.name github-actions[bot] + git config user.email 41898282+github-actions[bot]@users.noreply.github.com + - uses: actions/setup-python@v5 + with: + python-version: 3.x + - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV + - uses: actions/cache@v4 + with: + key: mkdocs-material-${{ env.cache_id }} + path: .cache + restore-keys: | + mkdocs-material- + - run: pip install mkdocs-material 'mkdocstrings[python]' + - run: mkdocs gh-deploy --force +``` + +## Использование + +### Добавление страниц +В корне папки `docs` создайте файл `index.md`. Это будет главная страница документации. Для добавления новой страницы создайте новый файл с расширением `.md` в папке `docs`. + +Таким образом, структура проекта документации может выглядеть следующим образом: + +``` + mkdocs.yml # The configuration file. + docs/ + index.md # The documentation homepage. + user-guide/ + getting-started.md + installation.md + api-reference.md + mymodule.md + mypackage.md + ... # Other markdown pages, images and other files. +``` + +### Добавление изображений +Для добавления изображений, их можно поместить в папку `docs` или в папку `docs/images`. Для добавления изображения на страницу документации, используйте следующий синтаксис: + +```markdown +![Alt text](path/to/image.png) +``` + +### Остальное +Так как MkDocs полностью поддерживает markdown, вы можете использовать все возможности markdown для форматирования текста, добавления ссылок, списков, таблиц и т.д. +Однако, для использования некоторых возможностей, может понадобится установка расширений через поле `markdown_extensions` в `mkdocs.yml`. + +## Тестирование и развертывание + +### Тестирование +Для тестирования документации локально, выполните следующую команду: + +```bash +mkdocs serve +``` + +После выполнения команды, документация будет доступна по адресу, указанному в терминале. + +### Развертывание + +Для развертывания на GitHub Pages, достаточно просто запушить изменения в репозиторий. Документация будет доступна по адресу `https://myusername.github.io/myproject/`. + +## Заключение + +Для более подробных инструкций можно использовать: + +- [MkDocs](https://www.mkdocs.org/) +- [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) + +## Примеры + +Такая документация уже используется на одном из проектов лаборатории. Однако работа над проектом еще ведется, поэтому документация пока в начальном виде. Но уже можно посмотреть на интерфейс и некоторые страницы документации. + +- [applyBN (WIP)](https://anaxagor.github.io/applyBN/) diff --git a/tutorials/documentation.md b/tutorials/documentation_rtd.md similarity index 99% rename from tutorials/documentation.md rename to tutorials/documentation_rtd.md index 4cdeda3..a8e228f 100644 --- a/tutorials/documentation.md +++ b/tutorials/documentation_rtd.md @@ -1,4 +1,4 @@ -# Руководство по документированию проекта +# Руководство по документированию проекта - Read The Docs ## 1. Создание профиля Read The Docs