Integration with a django project

[cwittlinger]

I am trying to incorporate mkautodoc to my project which is based on django and django-rest-framework. I believe before mkautodoc can properly work, django.setup() has to be called.

Any advice on how to do this?

If I just include mkautodoc and try to create a docstring mkdocs crashes with:

django.core.exceptions.ImproperlyConfigured: Requested setting REST_FRAMEWORK, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.

[tomchristie]

I guess you’d need to set the DJANGO_SETTINGS_MODULE environment variable, before running mkdocs?

[cwittlinger]

Okay, apparently I was stupid and while debugging changed my .env file...stupid me...

Thanks for the help.

[tomchristie]

🤷‍♂️ Sorry I don’t know - not something I’m really able to help with.

[cwittlinger]

see my edited answer

[apelliciari]

hi @cw-intellineers @tomchristie

where would you call django.setup()?

because I have DJANGO_SETTINGS_MODULE filled but if:

• I don't put django.setup(), I have the error "django.core.exceptions.AppRegistryNotReady: Apps aren't loaded yet."
• i put django.setup() [I've not found any other "entrypoint" who can be customized for mkdocs] I get some weird error on circular imports on django-extensions field
  ImportError: cannot import name 'CreationDateTimeField' from partially initialized module 'django_extensions.db.fields' (most likely due to a circular import)

Can you help me? I'm lost.

Thanks

[jleclanche]

So … I came across this, and ended up with a workaround I'm so ashamed of I'm starting to be proud of it.

I created a file in docs/django_settings.py, which contains the settings I want to initialize with, as well as a call to django.setup() after said settings, and a dummy variable I called setup:

import os
import sys

docs_dir, _ = os.path.split(__file__)
sys.path.append(os.path.dirname(docs_dir))

SECRET_KEY = "."
INSTALLED_APPS = ["…"]

setup = None
import django  # noqa
from django.apps import apps  # noqa
from django.conf import settings  # noqa

if not apps.ready and not settings.configured:
    django.setup()

I'm setting DJANGO_SETTINGS_MODULE to docs.settings, which in theory should be enough, but it actually isn't: Depending on the piece of code that is being autodoc'd, the import cycle can sometimes erroneously detect a circular import and raise an ImportError due to partially initialized module. One such example would be:

1. Document ::: library.module.SomeClass
2. From library.module, import a django setting
3. django.setup() is called, which goes through importing every INSTALLED_APP's models.py
4. From library.models, import library.module
5. We're now in a circular import (even though we really aren't)

So to fix that, django.setup() would have to be called as the first thing autodoc does, so that we don't cycle back to the code that called the setting; usually that is done in the entrypoint. But autodoc doesn't have an entrypoint… soooo, I made one by adding the following code to my index.md:

<style type="text/css">
/* Hide the hack signature from the index. */
.autodoc { display: none; }
</style>

::: docs.django_settings.setup

Now as one of the first things autodoc does (as part of the first document it processes), mkautodoc will import the docs.django_settings module, which will trigger django.setup() and avoid breakage later on.