Автоматическая сборка документации Mkdocs в Travis CI

Question

Как именно я могу автоматически развернуть документацию Mkdocs в Travis CI?

Answer 1

Вот как можно автоматически развернуть документацию mkdocs. Просто следуйте 3 шагам ниже.

Шаг 1

Просто вставьте следующие фрагменты кода в соответствующие места в вашем .travis.yml конфигурационный файл:

language: python # Set the build language to Python

python: 3.6.7 # Set the version of Python to use

branches: master # Set the branch to build from

install:
    - pip install mkdocs # Install the required dependencies

before_deploy:
    - mkdocs build --verbose --clean --strict # Build a local version of the docs

deploy: # Deploy documentation to Github in the gh_pages branch
    provider: pages
    skip_cleanup: true
    github_token: $github_token
    local_dir: site
    on:
        branch: master

Шаг 2

Если вы используете тему mkdocs, это не mkdocs или же readthedocs затем выполните следующие шаги, чтобы установить его:

• Сценарий 1: тема устанавливается через pip (например, mkdocs-material)

  1. присоединять pip install mkdocs с другими пакетами, которые нужно установить, например, с mkdocs-material это было бы pip install mkdocs mkdocs-material pymdown-extensions pygments

• Сценарий 2: тема не устанавливается через pip (например, docskimmer)

  1. Удалить --strict аргумент от mkdocs build --verbose --clean --strict подавить возможную ошибку при использовании темы, которую нельзя установить через pip.

  2. Добавьте код, необходимый для настройки темы, в before_deploy раздел выше mkdocs build --verbose --clean

  Код в before_deploy раздел будет выглядеть так для docskimmer:

  before_deploy:
      - git clone https://github.com/hfagerlund/mkdocs-docskimmer.git # Clone the repo hosting the code
      - cp -r $PWD/mkdocs-docskimmer/mkdocs_docskimmer . # Copy the required code to the repo root
      - cp -r $PWD/mkdocs-docskimmer/mkdocs_docskimmer/. ./docs # Copy the required code to the docs folder
      - mkdocs build --verbose --clean # Build a local version of the docs
  

  Установка тем, недоступных через pip, может отличаться.

Шаг 3

Последний шаг - сообщить Travis CI учетные данные, необходимые для входа в учетную запись GitHub, чтобы внести изменения:

1. Если вы уже настроили токен личного доступа с помощью public_repo сфера, перейти к 11
2. Перейти на этот URL. Если это разрешится, перейдите к шагу 7. В противном случае продолжите эти инструкции, как обычно.
3. Зайдите в настройки вашей учетной записи Github
4. Нажмите Настройки разработчика
5. Нажмите Личные маркеры доступа.
6. Нажмите Создать новый токен.
7. Вам может потребоваться ввести пароль GitHub для авторизации создания
8. Под Token descriptionвыберите имя для вашего токена - это может быть что угодно; Я бы назвал это что-то вроде Travis CI так как вы можете использовать токен столько раз, сколько захотите.
9. Включить public_repo Объем / разрешение
10. Нажмите Generate token внизу страницы
11. Перейдите в настройки репозитория Travis CI, для которого вы хотите собрать документацию Mkdocs.
12. Создайте переменную среды со следующими настройками:
    • Название: github_token
    • Значение: <THE TOKEN YOU JUST GENERATED>
    • Показать значение в журнале сборки: No
13. Нажмите add

Послесловие

Вы сделали! Пожалуйста, не стесняйтесь задавать мне любые вопросы в комментариях.

Кроме того, если метод перестает работать или не работает, пожалуйста, сообщите мне в комментариях, и я исправлю это как можно скорее.

Answer 2

Развернуть ваш сайт MkDocs с помощью Travis очень просто (учитывая, что вы используете материальную тему)

Шаг 1: Создайте репозиторий для вашего проекта с 3 пустыми ветками с именами master, dev, gh-pages.

Шаг 2: Клонировать репозиторий и локальный и оформить заказ в ветку разработчика. Добавьте свой сайт MkDocs в свою ветку разработки на локальном компьютере. Добавьте каталог '/site' в git-ignore.(Т.е. не нажимайте.html) добавьте.travis.yml, указанный ниже, в репо. Переместите свой сайт в ветку разработчика.

Шаг 3. Поднимите запрос на перенос для мастера из ветки разработки

Шаг 4: Войдите в Travis и подключите там свои репозитории, добавьте переменную env 'git_token' в travis(используется в.travis.yml), ее значение вы можете получить из github.com -> settings-> dev settings -> токен личного доступа.

Шаг 5: Завершить / объединить пул-реквест с мастером. Он вызовет веб-хук, и Трэвис начнет сборку. После сборки ваши сгенерированные html-файлы будут отправлены в ветку gh-pages.

Шаг 6: перейдите в настройки репозитория и настройте сайт git-hub pages для загрузки из ветки gh-pages.

Готово

.travis.yml

language: python # Set the build language to Python

python: 3.6 # Set the version of Python to use

branches: master # Set the branch to build from

install:
    - pip install mkdocs mkdocs-material pymdown-extensions pygments # Install the required dependencies

script: true # Skip script (Don't use this if one already exists)

before_deploy:
    - mkdocs build --verbose --clean --strict # Build a local version of the docs

deploy: # Deploy documentation to Github in the gh_pages branch
    provider: pages
    skip_cleanup: true
    github_token: $github_token
    local_dir: site
    on:
        branch: master