В каких файлах я должен указывать VCS игнорировать при использовании Sphinx для документации?

Я хочу начать использовать Sphinx для документирования моего проекта. Я сказал Sphinx использовать отдельные директории источника и сборки во время sphinx-quickstart. Теперь мой макет каталога выглядит следующим образом:

MyProject/
    myproject/
        __init__.py
        mymodule.py
    docs/
        source/
            .static/
            .templates/
            conf.py
            index.rst
        build/
        Makefile

Какие файлы должны быть исключены из репозитория VCS для проекта Sphinx (т.е. поскольку я использую Git, что я должен добавить в мой файл .gitignore)? Например, следует ли игнорировать каталог docs/build/, чтобы изменения в HTML-страницах, сгенерированных из Sphinx, не отслеживались?

Ответы

Ответ 1

Если вы посмотрите на содержимое Makefile, вы увидите что-то следующее:

BUILDDIR      = build

...

clean:
    -rm -rf $(BUILDDIR)/*

Это означает, что make clean просто удаляет каталог build, поэтому в отношении управления версиями игнорирование содержимого каталога build должно быть достаточно, как вы уже подозревали.

Ответ 2

Если вы создадите новый проект в GitHub, он предложит вам создать файл .gitignore с поддержкой Python. Этот файл включает одну ссылку в файлы, сгенерированные Sphinx:

# Sphinx documentation
docs/_build/

Примечание. Предполагается, что вы принимаете значения по умолчанию при запуске sphinx-quickstart. Возможно, вам придется настроить его в зависимости от того, как вы ответили на эти вопросы:

  • Корневой путь:

    Enter the root path for documentation.
> Root path for the documentation [.]:

    Определяет путь хранения документации. Если вы сделали что-то другое, кроме docs, вам необходимо обновить .gitignore соответственно.

  • Каталог сборки:

    You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]:

    Если вы ответили n (по умолчанию), то Sphinx создаст каталог сборки <root>/_build (ваши исходные файлы будут храниться непосредственно в <root>/).

    Если вы ответили y, то Sphinx создаст каталог сборки в <root>/build (ваши исходные файлы будут сохранены в <root>/source).

    Обратите внимание на наличие/отсутствие ведущего подчеркивания; убедитесь, что соответствующий шаблон в вашем .gitignore соответствует.