How to use Django specific markup in the docstrings.

[Anuj Sharma]

I am using Sphinx to generate documentation from the docstrings defined in the models, views, etc files.

At a few places, I have used Django specific markup for creating reference link. Same is documented in the [writing-documentation](​https://docs.djangoproject.com/en/dev/internals/contributing/writing-documentation/#django-specific-markup)

Ex.

The length is defined in the :setting:`URL_ID_LENGTH`

But while generating the documentation using

make html

it gives an error as

:docstring of app.models.Class.function:4: WARNING: Unknown interpreted text role "setting".

How to use the Django specific markups? This should be added to the documentation as well.

Here is an issue on StackOverflow: ​https://stackoverflow.com/q/56803854/3719167

[Carlton Gibson]

This is not a support channel. Please see TicketClosingReasons/UseSupportChannels.

(Google sphinx extensions. Look in django/docs/conf.py and django/docs/_ext/djangodocs.py)

This should be added to the documentation as well.

We already link to the RST docs.

[Adam Starrh]

Replying to Carlton Gibson:

This is not a support channel. Please see TicketClosingReasons/UseSupportChannels.

(Google sphinx extensions. Look in django/docs/conf.py and django/docs/_ext/djangodocs.py)

This should be added to the documentation as well.

We already link to the RST docs.

Please take a closer look at this.

To utilize the Django-Specific markup, developers must find, and import the djangodocs extensions into their Sphinx configuration. The RST docs can tell you where to add the extension, but shouldn't Django's docs at least tell you what the name of the extension is, and where to find it in order to add it? ​https://docs.djangoproject.com/en/dev/internals/contributing/writing-documentation/#getting-started-with-sphinx.

[Carlton Gibson]

...at least tell you what the name of the extension is, and where to find it in order to add it?

The Writing documentation section linked is about writing docs for Django itself, where it's already set up for you. (Is that the best location for Writing documention for your project?

So, maybe yes, an addition somewhere explaining that these extensions exist might be worth adding.

I'm happy to Accept this ticket on the basis that such a patch was provided, and then we could assess whether it looks good or not.
What I don't want to do is Accept it and then have it sit open for X years whilst nobody works on it.
(I hope that makes sense.)

As such, I'll close it as needsinfo — that info being "is a patch going to appear soon?". Please reopen, assign to yourself, and Accept if such a patch is incoming.