Как собрать документацию sphinx для проекта django - PullRequest
Новая
       43

Как собрать документацию sphinx для проекта django

15 голосов
/ 12 октября 2011

У меня есть проект django, который я документирую, используя reST в docstrings, чтобы выполнить следующие действия:

  1. Помочь diagloags в IDE
  2. Позже для создания документации HTML с использованием Sphinx

Моя документация правильно отображается в IDE (PyCharm), однако я не могу настроить Sphinx для генерации HTML-документации для меня.

Вот структура моего проекта 

+--------------------------------------------+
|  /saassapp         # django project path   |
|     /docs          # dir for sphinx        |
|        conf.py     # sphinx config file    |
|        ...                                 |
|     settings.py    # django settings       |
|     /studyview     # django app            |
|        ...
|     ...                                    |
+--------------------------------------------+

Есть идеи?Пример файла conf.py был бы очень полезен.Спасибо.

РЕДАКТИРОВАТЬ

Мой проект называется saassapp, а модуль, для которого я пытаюсь создать документ, называется studyview.

Ответы [ 6 ]

17 голосов
/ 17 ноября 2015

Функции миграции, представленные в Django 1.7, не позволяют предыдущим ответам работать с более новыми версиями. Вместо этого вам придется сделать ручную настройку. Аналогично всем предыдущим ответам, вам сначала нужно убедиться, что Django может найти ваши настройки, а затем позвонить django.setup(), чтобы загрузить настройки и настроить ваши модели. Добавьте это в conf.py вашего * проекта Sphinx: 

os.environ['DJANGO_SETTINGS_MODULE'] = 'projectname.settings'
import django
django.setup()
14 голосов
/ 19 ноября 2011

Добавьте следующее в ваш conf.py, и вам не нужно будет каждый раз устанавливать DJANGO_SETTINGS_MODULE: 

import sys, os

sys.path.append('/path/to/your/project') # The directory that contains settings.py

# Set up the Django settings/environment
from django.core.management import setup_environ
from myproject import settings

setup_environ(settings)
12 голосов
/ 23 июня 2014

С Django 1.6 я не мог использовать ответ @MikeRyan, так как from django.core.management import setup_environ устарел. Вместо этого я зашел в свой файл conf.py и добавил следующее: 

import sys
import os

sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
os.environ['DJANGO_SETTINGS_MODULE'] = 'dataentry.settings'
from django.conf import settings

Позвольте мне объяснить каждую строку:

  1. Я использовал относительный путь (двумя каталогами вверх), но вы можете пойти дальше и указать абсолютный путь, если хотите
  2. Мой проект называется dataentry, а файл settings.py находится внутри этой папки; измените имя (dataentry) на имя вашего проекта
4 голосов
/ 14 октября 2011

Я думаю, вы должны сообщить Sphinx о переменной окружения DJANGO_SETTINGS_MODULE.Так что 

export DJANGO_SETTINGS_MODULE=mysite.settings

(или как вам подходит)

Затем выполните 

make html

в том же терминальном сеансе.

0 голосов
/ 08 ноября 2017

Вам на самом деле не нужен отдельный settings модуль. Иногда его проще иметь (при тестировании и настройках общего доступа к документам), но не обязательно.

Это , как dj-stripe настраивает django для сфинкса . Здесь ключом является settings.configure вызов с INSTALLED_APPS, так как это единственный требуемый ключ настройки (если, конечно, вашему приложению не требуется больше): 

import django
from django.conf import settings
from django.utils.encoding import force_text
from django.utils.html import strip_tags

import djstripe  # noqa


# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# sys.path.insert(0, os.path.abspath('.'))
cwd = os.getcwd()
parent = os.path.dirname(cwd)
sys.path.append(parent)


settings.configure(
    INSTALLED_APPS=[
        "django.contrib.admin",
        "django.contrib.auth",
        "django.contrib.contenttypes",
        "django.contrib.sessions",
        "django.contrib.sites",
        "jsonfield",
        "djstripe",
    ],
    SITE_ID=1,
    STRIPE_PUBLIC_KEY=os.environ.get("STRIPE_PUBLIC_KEY", ""),
    STRIPE_SECRET_KEY=os.environ.get("STRIPE_SECRET_KEY", ""),
)


django.setup()
0 голосов
/ 11 октября 2017

Поздно, но с использованием Django>=1.9 и sphinx>=1.6.4 установить путь, эквивалентный проекту BASE_DIR в conf.py

import django
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(__file__))))
os.environ["DJANGO_SETTINGS_MODULE"] = "project.settings"
django.setup()
...