Блог

Недавно я написал пакет Python и сгенерировал некоторую документацию, используя Sphinx. Я добавил документацию в репозиторий GitHub проекта и теперь хотел бы разместить статические страницы. Я прочитал в Интернете, что вы можете использовать страницы GitHub для этого.

Таким образом, я убедился, что включил страницы GitHub для общедоступного репозитория и выбрал docs папку для корневого каталога.

В настоящее время я сталкиваюсь с:

 404 Files not Found Error 
 

каждый раз, когда я пытаюсь получить доступ к ссылке проекты.

Текущая иерархия каталога docs структурирована следующим образом:

 - docs
   - source
       - index.rst
       - installation.rst
       - conf.py
       - examples.rst
   - Makefile
 

Я прочитал несколько вещей в Интернете, таких как это, которые, по-видимому, подразумевают, что проблема может возникнуть, если у вас есть подкаталоги (т. е. для меня в этом случае проблема может заключаться в том, что у меня есть отдельный source каталог в docs каталоге, а не только все файлы в одном каталоге). Я думаю, что это может быть проблемой, единственная часть — я не уверен, как это решить.

Должен ли я выбрать все файлы в source подкаталоге и переместить их в каталог docs с Makefile помощью? Как мне это сделать? Это должна быть структура, которую я использую для отслеживания их в Git, поэтому, возможно, мне придется изменить способ их отслеживания Git?

Любые ссылки на ресурсы или примеры были бы весьма признательны.

Редактировать: я смотрю на это репозиторий, в частности, там, где кажется, что документы размещаются на страницах GitHub и загружаются в репозиторий в .rst формате файла. Может быть, это как-то связано с Jekyll или что-то в этом роде?

Обновлено:

Редактирование 2: в итоге я удалил .rst файлы из репозитория (отследил их из git) и поместил .html файлы в каталог сборки. Поскольку GitHub Pages требует, чтобы документы находились в корневом /docs каталоге, я просто скопировал .html файлы в /docs корневую папку в репозитории. Однако проблема, с которой я сталкиваюсь, заключается в том, что сейчас тема строится неправильно, и я получаю только скелетную версию index.html сборки.

Я определил, что это, вероятно, как-то связано с _static тем, что файлы не включены или некоторые другие файлы, необходимые для правильной сборки темы. Мой вопрос в том, как должна выглядеть структура каталогов этого проекта?

Есть ли у нас, например,:

 /docs
   _static
   index.html
 

Какие файлы нам нужно включить, чтобы документация Sphinx была собрана правильно, и на каком уровне каждый из файлов / папок должен находиться в /docs корневом каталоге?

Другими словами, я получаю проблему, связанную с темой, подробно описанную в этом сообщении в блоге. Я попытался просто переместить _static папку вверх по каталогу на уровень с index.html файлом, но это, похоже, не решило проблему.

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

Фактический рабочий процесс создания / развертывания документа находится в конфигурации CircleCI, https://github.com/amueller/dabl/blob/main/.circleci/config.yml

Он просто выполняет следующее,

1. Используется build_doc.sh для создания HTML-страниц и других артефактов.
2. Используется push_doc.sh для копирования всех артефактов в репозиторий с поддержкой GitHub Pages, https://github.com/amueller/amueller.github.io

Итак, как я уже прокомментировал, этот автор размещает только HTML-страницы и другие артефакты, сгенерированные Sphinx (поскольку это то, чего желает GitHub Pages), но не реструктурированные текстовые исходные файлы.