Установка Sphinx на App Engine – возможно?

Следуя моему прошлогоднему вопросу о документации, теперь я хочу начать работу и попробовать Python- Sphinx для составления документации разработчика для PHP CMS, над которой я работал.

Вместо того чтобы настраивать Python локально на моей рабочей станции, я хотел бы запустить его на общедоступном веб-сервере с самого начала. У всех пакетов веб-хостинга у меня есть доступ к запуску в стеке LAMP, и я неохотно покупаю хостинг на базе Python. Я очень заинтересован в Google App Engine, бесплатные квоты, которые они предоставляют, будут делать для меня сто раз, и даже если нет, их цена выглядит очень разумно.

Теперь у меня есть нулевое знание Python – заставить Сфинкса работать, это мой первый контакт с ним – и очень мало времени. Насколько я понимаю, платформы и библиотеки python, которые предоставляет App Engine, очень совместимы со стандартной библиотекой Python, но не идентичны .

Поэтому мой вопрос:

  • Может ли Sphinx запускаться в App Engine?

  • Устанавливает Sphinx в App Engine так же просто, как если бы я установил его поверх обычной установки Python? Или среда App Engine требует настройки исходного кода, который я не могу выполнить в разумные сроки с моим текущим уровнем Python?

  • Должен ли я сначала устанавливать Sphinx на локальном сервере и «обычный» стек Python?

  • Кто-нибудь знает какие-нибудь полезные советы, учебные пособия или другие ресурсы для этого?

Интересный проект! Основная проблема, с которой вы столкнетесь, – это доступ к файловой системе: файловая система в App Engine доступна только для чтения, и, основываясь на поиске источника, Sphinx довольно жестко закодирован для использования файловой системы для вывода. Он также ожидает, чтобы прочитать файл конфигурации и ввести файлы из локальной файловой системы, что сделало бы строительные документы для чего-либо, кроме проектов, связанных с приложением сложным.

Можно обойти это, но для этого потребуется написать простую виртуальную файловую систему, которая использует хранилище данных App Engine, и использовать команду monkeypatching, чтобы заставить ее работать с обычным файловым интерфейсом Python. Это довольно продвинутый проект для нового проекта Python!

Еще одна вещь, которую вы, возможно, захотите рассмотреть, если вы размышляли над тем, чтобы позволить пользователям загружать проекты для документирования: конфигурационный файл Sphinx находится на Python, поэтому его выполнение может быть опасным – пользователь может делать неприятные вещи в вашем приложении со вредоносной конфигурацией !

Вам не нужно устанавливать Sphinx на GAE вообще.

Вы используете Sphinx для создания каталога статических HTML, CSS и JS. Когда этот шаг будет завершен, вы просто загрузите вывод из Sphinx – в полном объеме.

Выход из Sphinx (HTML, CSS и JS) просто подается с одного места . Вы загружаете документацию с того места, где вы ее создали, в GAE в качестве статических файлов и обслуживаете их. Готово.

В Sphinx нет никакого аспекта «установить на веб-сервере». Sphinx не является веб-приложением; он не запускается на вашем веб-сервере. Вы запустите его в разработке, чтобы опубликовать документацию на HTML, LaTeX или что-то еще. Создав статические файлы HTML, вы больше не нуждаетесь ни в одной части Sphinx.

Может ли Sphinx запускаться в App Engine?

Я полагаю, что это возможно, но вам никогда не понадобится.

Устанавливает Sphinx в App Engine так же просто, как …

Это не имеет значения, потому что вы его не устанавливаете. Вы устанавливаете его на свою рабочую станцию ​​и используете ее на своей рабочей станции.

Должен ли я сначала устанавливать Sphinx на локальном сервере и «обычный» стек Python?

Не устанавливайте его на сервере. Установите его на свою рабочую станцию.

Кто-нибудь знает какие-нибудь полезные советы, учебные пособия или другие ресурсы для этого?

Если под «этим» вы подразумеваете «установку на веб-сервере», тогда ответ «нет». Он не устанавливается на веб-сервере. Таким образом, для «установки на веб-сервере» нет инструкций, учебных пособий или ресурсов.

Если «этим» вы подразумеваете «создание документации с Sphinx», тогда ответ «что не так с http://sphinx.pocoo.org ? Что им не хватает?


Я бы хотел, чтобы «движок» Sphinx превращал вход (состоящий из файлов reST) в HTML / CSS / JS, чтобы быть доступным из любого места, чтобы сделать меня (и возможных других участников) независимым от конкретной рабочей станции.

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

обслуживать сгенерированную документацию из того же места.

Верный. После того, как вы загрузите источник, внесите изменения, обновите документ и зафиксируете изменения, вы загрузите полученный документ, чтобы он был подан из одного и только одного места.

Sphinx – это компилятор. Это не «веб-движок». Это простой компилятор, который просто компилирует вашу документацию в HTML, чтобы ее можно было обслуживать.

Разница между развертыванием локально через dev_appserver и удаленно с помощью appcfg была – по моему опыту – ограничена какой из двух выполняемых мной команд. Тем не менее, у меня нет опыта работы с Sphinx.

Sphinx компилирует документацию, запуская ее на веб-сервере, имеет такой же смысл, как и запуск gcc на веб-сервере.