[Django] #23868: dumpdata options documentation isn't correctly formatted for some options
Django
--------------------------------------+--------------------
Reporter: kezabelle | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+--------------------
Specifically, [https://docs.djangoproject.com/en/dev/ref/django-admin
/#dumpdata-app-label-app-label-app-label-model dumpdata <app_label
app_label ...>] gives `--format`, `--pks`, `--indent` etc their own
headings, but `--exclude` and `--database` are formatted in such a way
that they look like addendums to the `--indent` documentation.
Also, `--pks` lacks a demonstrative example that `--format` and `--indent`
provide (eg: `<pk,pk,pk ...>` or whatever). I'd suggest that example
argument formats should also be given to `--exclude` and `--database`, if
hoisted to headings.
An argument could be made that because both are common options (documented
under common options) they needn't even be covered here, I suppose, though
given `dumpdata` exports unmanaged models (which it may not be able to)
I'd say the `--exclude` is pertinent. If hoisting to their own headings is
undesirable because they're already headings elsewhere, the paragraphs
should probably be moved to the preamble which includes explaining `--all`
as prose.
--
Ticket URL: <https://code.djangoproject.com/ticket/23868>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: kezabelle | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by timgraham):
* needs_better_patch: => 0
* needs_docs: => 0
* needs_tests: => 0
* stage: Unreviewed => Accepted
Comment:
As you alluded to, the problem is that because they are common options, we
can't include them multiple times using `.. django-admin-option::``. We
can improve things however you like though.
--
Ticket URL: <https://code.djangoproject.com/ticket/23868#comment:1>
Django
Reporter: kezabelle | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by akulakov):
I think it would make sense if common options would be always given either
before the specific options or after; it's better to have them before
specific options because otherwise they do look like they're part of the
option that precedes them.
Alternatively there may be a short paragraph before the first option that
simply lists the common option names and links to common options section.
The downside of this approach is that common options like --database and
--exclude are very important and perhaps deserve at least a short
description in each section. On the third hand, they are more or less
self-descriptive so perhaps they don't. A reader probably won't miss them
anyway since the name of the option is bolded.
--
Ticket URL: <https://code.djangoproject.com/ticket/23868#comment:2>
Django
Reporter: kezabelle | Owner: timgraham
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by timgraham):
* status: new => assigned
* owner: nobody => timgraham
Comment:
I think we need to modify the `parse_django_adminopt_node()` function in
`docs/_ext/djangodocs.py` to allow declaring the options like this `..
django-admin-option:: runserver --nothreading` (with the command name).
That removes the restriction that commands cannot share options.
Unfortunately, this will require updating all the documentation references
to options as well.
I'll try to do this as it's blocking #25735 which adds a `--tag` option to
the `test` command which is already implemented by `check`.
--
Ticket URL: <https://code.djangoproject.com/ticket/23868#comment:3>
Django
Reporter: kezabelle | Owner: timgraham
Type: | Status: assigned
Cleanup/optimization |
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by timgraham):
This is coming along and I hope to finish tomorrow:
[https://github.com/django/django/pull/5971 WIP PR]
--
Ticket URL: <https://code.djangoproject.com/ticket/23868#comment:4>
Django
Reporter: kezabelle | Owner: timgraham
Type: | Status: assigned
Cleanup/optimization |
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by timgraham):
* has_patch: 0 => 1
Comment:
Should be ready for review now. The other task that must be completed
before merging this is figuring out why the docs builds crashes on
djangoproject.com with Sphinx 1.3+.
--
Ticket URL: <https://code.djangoproject.com/ticket/23868#comment:5>
Django
Reporter: kezabelle | Owner: timgraham
Type: | Status: assigned
Cleanup/optimization |
Severity: Normal | Resolution:
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by charettes):
* stage: Accepted => Ready for checkin
--
Ticket URL: <https://code.djangoproject.com/ticket/23868#comment:6>
Django
Reporter: kezabelle | Owner: timgraham
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Tim Graham <timograham@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"e519aab43a419589e92fe284e4ce2f2e034aec6a" e519aab4]:
{{{
#!CommitTicketReference repository=""
revision="e519aab43a419589e92fe284e4ce2f2e034aec6a"
Fixed #23868 -- Added support for non-unique django-admin-options in docs.
Also documented missing short command line options to fix #24134. This
bumps
the minimum sphinx version required to build the docs to 1.3.4.
Thanks Simon Charette for review.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/23868#comment:7>
Django
Reporter: kezabelle | Owner: timgraham
Type: | Status: closed
Cleanup/optimization |
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"d7a6086825d4a308955e792f65fdd9b5f714a505" d7a60868]:
{{{
#!CommitTicketReference repository=""
revision="d7a6086825d4a308955e792f65fdd9b5f714a505"
[1.9.x] Fixed #23868 -- Added support for non-unique django-admin-options
in docs.
Also documented missing short command line options to fix #24134. This
bumps
the minimum sphinx version required to build the docs to 1.3.4.
Thanks Simon Charette for review.
Backport of e519aab43a419589e92fe284e4ce2f2e034aec6a from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/23868#comment:8>