Opened 5 years ago

Closed 5 years ago

#30607 closed Cleanup/optimization (needsinfo)

How to use Django specific markup in the docstrings.

Reported by: Anuj Sharma Owned by: nobody
Component: Documentation Version: 2.2
Severity: Normal Keywords: writing-documentation, Django-specific-markup
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description (last modified by 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

Change History (5)

comment:1 by Anuj Sharma, 5 years ago

Description: modified (diff)

comment:2 by Anuj Sharma, 5 years ago

Description: modified (diff)

comment:3 by Carlton Gibson, 5 years ago

Resolution: invalid
Status: newclosed

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.

Last edited 5 years ago by Carlton Gibson (previous) (diff)

in reply to:  3 comment:4 by Adam Starrh, 5 years ago

Resolution: invalid
Status: closednew

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 add "djangodocs", to the extensions in their Sphinx configuration. The RST docs can tell you where to add the extension, but Django's docs should at least tell you what the name of the extension is, no? https://docs.djangoproject.com/en/dev/internals/contributing/writing-documentation/#getting-started-with-sphinx.

Version 0, edited 5 years ago by Adam Starrh (next)

comment:5 by Carlton Gibson, 5 years ago

Resolution: needsinfo
Status: newclosed

...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.

Note: See TracTickets for help on using tickets.
Back to Top