[Django] #30607: How to use Django specific markup in the docstrings.
Django
-------------------------------------+-------------------------------------
Reporter: Anuj | Owner: nobody
Sharma |
Type: | Status: new
Cleanup/optimization |
Component: | Version: 2.2
Documentation | Keywords: writing-
Severity: Normal | documentation, Django-specific-
Triage Stage: | markup
Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------+-------------------------------------
I am using Sphinx to generate documentation from the docstrings defined in
the modes, view, 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
--
Ticket URL: <https://code.djangoproject.com/ticket/30607>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
-------------------------------------+-------------------------------------
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 2.2
Severity: Normal | Resolution:
Keywords: writing- | Triage Stage:
documentation, Django-specific- | Unreviewed
markup |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Old description:
> I am using Sphinx to generate documentation from the docstrings defined
> in the modes, view, 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
New description:
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
--
--
Ticket URL: <https://code.djangoproject.com/ticket/30607#comment:1>
Django
-------------------------------------+-------------------------------------
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 2.2
Severity: Normal | Resolution:
Keywords: writing- | Triage Stage:
documentation, Django-specific- | Unreviewed
markup |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Old description:
> 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
New description:
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
--
--
Ticket URL: <https://code.djangoproject.com/ticket/30607#comment:2>
Django
-------------------------------------+-------------------------------------
Cleanup/optimization |
Component: Documentation | Version: 2.2
Keywords: writing- | Triage Stage:
documentation, Django-specific- | Unreviewed
markup |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: new => closed
* resolution: => invalid
Comment:
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`)
--
Ticket URL: <https://code.djangoproject.com/ticket/30607#comment:3>
Django
-------------------------------------+-------------------------------------
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 2.2
Severity: Normal | Resolution:
documentation, Django-specific- | Unreviewed
markup |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: closed => new
* resolution: invalid =>
Comment:
Replying to [comment:3 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/30607#comment:4>
Django
-------------------------------------+-------------------------------------
Cleanup/optimization |
Component: Documentation | Version: 2.2
Keywords: writing- | Triage Stage:
documentation, Django-specific- | Unreviewed
markup |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: new => closed
* resolution: => needsinfo
Comment:
> ...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.
--
Ticket URL: <https://code.djangoproject.com/ticket/30607#comment:5>