Строительная документация¶
Прежде чем вносить какие-либо изменения в документацию BeeWare, рекомендуется убедиться, что вы можете скомпилировать существующую документацию.
Прежде чем создавать документацию, необходимо настроить среду разработки.
Вы должны иметь установленный интерпретатор Python 3.13
и доступный в вашем пути (т. е. python3.13 должен
запускать интерпретатор Python 3.13).
BeeWare использует tox для создания документации. Следующие команды
tox должны выполняться из того же места, что и файл tox.ini, который
находится в корневом каталоге проекта.
Предварительный просмотр документации в режиме реального времени¶
Для ускорения редактирования документации BeeWare имеет режим «предварительного просмотра».
Предварительный просмотр будет создаваться с предупреждениями!
Live Serve доступен для итерации обновлений вашей документации. Во время
обновления вы можете столкнуться с проблемой разметки. Проблемы, обозначенные
как WARNING, приведут к сбою стандартной сборки, однако Live Serve настроен
так, что он отображает предупреждения в консольном выводе, продолжая сборку. Это
позволяет вам выполнять итерацию без необходимости перезапуска Live Preview.
WARNING отличается от ERROR. Если вы введете проблему, которая считается
ERROR, работа в режиме реального времени будет прервана, и потребуется
перезапуск. Работа не возобновится до тех пор, пока проблема WARNING не будет
решена.
Чтобы запустить рабочий сервер:
(venv) $ tox -e docs-live
(venv) $ tox -e docs-live
(venv) C:\...>tox -e docs-live
Это создаст документацию, запустит веб-сервер для обслуживания документации и будет отслеживать файловую систему на предмет любых изменений в исходном коде документации.
После запуска сервера в консоли появится примерно следующее сообщение:
INFO - [11:18:51] Serving on http://127.0.0.1:8000/
Откройте браузер и перейдите по указанному URL-адресу. Теперь вы можете приступить к итерации документации. При обнаружении изменений документация будет перестроена, а любой браузер, просматривающий измененную страницу, будет автоматически обновлен.
docs-live — это первый шаг
Запуск docs-live для работы с живым сервером предназначен для первоначальной
итерации. Вы должны всегда запускать локальную сборку перед отправкой запроса
на вытягивание.
Локальная сборка¶
После завершения итерации вам необходимо будет выполнить локальную сборку документации. Этот процесс сборки запрограммирован на сбой в случае обнаружения каких-либо проблем с разметкой. Это позволяет вам обнаружить все, что вы могли пропустить на рабочем сервере.
Создание локальной сборки¶
Чтобы сгенерировать локальную сборку:
(venv) $ tox -e docs
(venv) $ tox -e docs
(venv) C:\...>tox -e docs
Результат этой сборки будет находиться в каталоге _build в корневом каталоге
проекта.
Создание локальной переведенной сборки¶
Документация BeeWare переведена на несколько языков. Обновления английской документации могут привести к проблемам в сборках на других языках. Перед отправкой запроса на извлечение важно проверить, что все сборки работают.
Чтобы сгенерировать сборку всех доступных переводов:
(venv) $ tox -e docs-all
(venv) $ tox -e docs-all
(venv) C:\...>tox -e docs-all
Результаты компиляции каждого языка будут находиться в соответствующем каталоге
_build/html/<languagecode>, где <languagecode> — это двух- или пятизначный
код языка, связанный с конкретным языком (например, fr для французского, it
для итальянского и т. д.).
Если вы обнаружили проблему с одной сборкой, вы можете запустить эту сборку
отдельно, выполнив tox -e docs-<languagecode>. Например, чтобы скомпилировать
только французскую документацию, выполните:
(venv) $ tox -e docs-fr
(venv) $ tox -e docs-fr
(venv) C:\...>tox -e docs-fr
Результат одноязычной сборки будет находиться в каталоге _build.
Проверка документации¶
Процесс сборки выявит проблемы Markdown, но BeeWare выполняет некоторые дополнительные проверки стиля и форматирования, известные как «линтинг». Чтобы запустить проверки линтинга:
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
Это подтвердит, что документация не содержит:
- неработающие гиперссылки
- ошибочно написанные слова
Если правильное написание слова распознается как ошибочное, добавьте это слово в
список в docs/spelling_wordlist. Это добавит слово в словарь программы
проверки орфографии. При добавлении в этот список помните:
- Мы предпочитаем американское правописание, с некоторыми отступлениями для программистского сленга (например, «apps») и использования существительных в качестве глаголов (например, «scrollable»).
- При упоминании названия продукта следует использовать предпочтительный вариант написания с заглавной буквы (например, «macOS», «GTK», «pytest», «Pygame», «PyScript»).
- Если термин используется «в качестве кода», то его следует указывать в
кавычках (
like this) вместо добавления в словарь.
После успешного создания документации вы готовы к написанию документации.