[Django] #17638: Link up topic guides with API reference
Django
-------------------------------+--------------------
Reporter: oinopion | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: SVN
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+--------------------
There is one thing bothering me with Django documentation: it's split
between topic guides and API reference. Often while googling I get to
wrong one and it's not always easy to find another. There should be an
easy way to do that: a link at the top/bottom/sidebar. And this way should
probably be somehow automatic, so new pages are connecte automatically.
--
Ticket URL: <https://code.djangoproject.com/ticket/17638>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Type: Uncategorized | Status: new
Component: Documentation | Version: SVN
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Changes (by lrekucki):
* needs_better_patch: => 0
* stage: Unreviewed => Accepted
* needs_tests: => 0
* needs_docs: => 0
Comment:
Can't hurt.
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:1>
Django
Reporter: oinopion | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
-------------------------------+------------------------------------
Changes (by timo):
* easy: 0 => 1
Comment:
I think this is done manually in several places and I think we should
probably keep it that way as automating it is not likely to be worth the
effort.
Auditing the current links between topics and reference guides and adding
any that are missing would be a good task for a new contributor.
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:3>
Django
Reporter: oinopion | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------+------------------------------------
* cc: internet@… (added)
Comment:
I don't mind taking a look at this if someone could add an example where
this is done well, and an example where this is done badly so I know what
I'm looking to correct and what I'm aiming for.
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:4>
Django
Reporter: oinopion | Owner: gmohre
Type: New feature | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------+------------------------------------
* status: new => assigned
* owner: nobody => gmohre
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:5>
Django
Reporter: oinopion | Owner: gmohre
Type: New feature | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------+------------------------------------
Comment (by gmohre):
There are currently three styles of linking from an API reference page to
the appropriate topic.
* A link within the first paragraph which leads to the canonical topic
page.
ex. https://docs.djangoproject.com/en/1.5/ref/class-based-views/
* Inline links within subtopics of an API reference which lead to a
subtopic on a topic page, which may be part of a different module.
ex. https://docs.djangoproject.com/en/1.5/ref/django-
admin/#s-compilemessages
* A div with a class of "admonition" which contains links to a mix of
topic and API reference pages.
ex. https://docs.djangoproject.com/en/1.5/ref/signals/
I think it would be useful to wrap all links to the canonical topic pages
in an admonition styled div. Wrapping links in a styled div within a
subtopic may be disruptive to the flow of the document. Perhaps these
should all be collected in a admonition styled div at the bottom of a
page, though this goes against DRY principles.
Counter to this suggestion, the DRY subtopic of the design philosophies
page has an admonition styled div within the subtopic, linking to an
external resource.
https://docs.djangoproject.com/en/1.5/misc/design-philosophies/#s-don-t
-repeat-yourself-dry
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:6>
Django
Reporter: oinopion | Owner:
Type: New feature | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------+------------------------------------
* owner: gmohre =>
* status: assigned => new
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:7>
Django
Reporter: oinopion | Owner:
Type: New feature | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------+------------------------------------
Comment (by anubhav9042):
I think the proposed thing could be explained in a more better way.
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:8>
Django
Reporter: oinopion | Owner: lkitchner
Type: New feature | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by lkitchner):
* owner: => lkitchner
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:9>
Django
Reporter: oinopion | Owner:
Type: New feature | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------+------------------------------------
* owner: lkitchner =>
* status: assigned => new
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:10>
Django
Reporter: oinopion | Owner:
Type: New feature | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------+------------------------------------
Comment (by mcintyre1994):
I'd be interested to look at this as a first bug, but I'm a little unclear
exactly what is wanted. I've put together a quick screenshot of
[http://imgur.com/YP3NbIB class based views introductory material]
([https://docs.djangoproject.com/en/1.5/topics/class-based-views/
current]) and [http://imgur.com/Nt3aXLI class based views API reference]
([https://docs.djangoproject.com/en/1.5/ref/class-based-views/ current])
using the admonition unit for see also links at the top of each. If I did
something like that for each page in API ref/intro material with links to
other material at the top, would that be vaguely along the right lines?
I'm not really sure about the second example mentioned above, inline links
look fine to me as they are.
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:11>
Django
Reporter: oinopion | Owner: anonymous
Type: New feature | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by mcintyre1994):
* status: new => assigned
* owner: => anonymous
Comment:
Implemented per my above screenshots for them pages, can be seen here.
https://github.com/mcintyre94/django/tree/ticket_17638
Happy to run through some other files and do the same thing if that's
what's wanted here, but I'd appreciate some feedback first. ASsigned to
myself, hope that's alright!
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:12>
Django
Reporter: oinopion | Owner: anonymous
Type: New feature | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------+-------------------------------------
Comment (by mcintyre1994):
(Created an account, same mcintyre1994 as above)
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:13>
Django
Reporter: oinopion | Owner: anonymous
Type: New feature | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------+-------------------------------------
Comment (by timo):
I don't think the table of contents should be moved into the "See Also"
boxes, otherwise, this looks ok.
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:14>
Django
Reporter: oinopion | Owner: jarus
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by jarus):
* owner: anonymous => jarus
* type: New feature => Cleanup/optimization
Comment:
There was no action since 4 months, I hope it's okay that I adopt this
ticket.
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:15>
Django
Reporter: oinopion | Owner: jarus
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by jarus):
See also #23106
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:16>
Django
Reporter: oinopion | Owner: jarus
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* has_patch: 0 => 1
Comment:
Pull request: https://github.com/django/django/pull/2975
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:17>
Django
Reporter: oinopion | Owner: jarus
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* needs_better_patch: 0 => 1
Comment:
The idea was to do this for all pages that have both topic and ref docs,
not just for class based views.
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:18>
Django
Reporter: oinopion | Owner: jarus
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by jarus):
I added a few more links between pages which make sense in my eyes.
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:19>
Django
Reporter: oinopion | Owner: jarus
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* needs_better_patch: 1 => 0
Comment:
Don't forget to uncheck "Patch needs improvement" so the ticket goes back
in the review queue. I'll try to review and commit this soon, thanks.
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:20>
Django
Reporter: oinopion | Owner: jarus
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* needs_better_patch: 0 => 1
Comment:
The first '.. seealso::' box was introduced 2008 and the box was at the
bottom of the page in forms/topics/index and I think that would be better
like the solution done in here. (all boxes at the top)
Also one box is duplicated. (the one in forms/topics/index is at the top
and the bottom ;))
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:21>
Django
Reporter: oinopion | Owner: jarus
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by timo):
I think it makes sense to put the "see also" boxes at the bottom of the
topic guides (after you've read the introductory material, you might be
interested in the reference guides). For the reference guides, I suggest
we omit the "see also" boxes, but have the link in the introductory
paragraph as is already done in a couple places (e.g. For "introductory
material, see :doc:`/topics/class-based-views/index`.")
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:22>
Django
Reporter: oinopion | Owner:
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* owner: jarus =>
* status: assigned => new
Comment:
Someone else is welcome to pick where jarus left off.
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:23>
Django
Reporter: oinopion | Owner:
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* keywords: => afraid-to-commit
Comment:
I've marked this ticket as especially suitable for people following the
'''Don't be afraid to commit tutorial''' at the DjangoCon US 2014
sprints.
If you're tackling this ticket, please don't hesitate to ask me for
guidance if you'd like any, either at the sprints themselves, or here or
on the Django IRC channels, where I can be found as ''EvilDMP''.
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:24>
Django
Reporter: oinopion | Owner: duane9
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: afraid-to-commit | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* owner: => duane9
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:25>
Django
Reporter: oinopion | Owner: duane9
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: afraid-to-commit | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by duane9):
Following comments and what has already been done, I added links to the
bottom of the topics pages for templates, settings, models, and migrations
that go to the corresponding reference pages. I also added links to the
top of ref/settings and ref/migration-operations that go to the
corresponding topics pages. https://github.com/django/django/pull/3285
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:26>
Django
--------------------------------------+------------------------------------
Reporter: oinopion | Owner: duane9
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: afraid-to-commit | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"054bdfeff113459a48974d08098915431d0a093d"]:
{{{
#!CommitTicketReference repository=""
revision="054bdfeff113459a48974d08098915431d0a093d"
Fixed #17638 -- Added crosslinks between topic and reference guides.
Thanks oinopion for the suggestion and jarus for the initial patch.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:27>
Django
--------------------------------------+------------------------------------
Reporter: oinopion | Owner: duane9
Type: Cleanup/optimization | Status: closed
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: afraid-to-commit | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by Tim Graham <timograham@…>):
In [changeset:"8c0851051d46d62f3bdc1efcbb1614103f1629a3"]:
{{{
#!CommitTicketReference repository=""
revision="8c0851051d46d62f3bdc1efcbb1614103f1629a3"
[1.6.x] Fixed #17638 -- Added crosslinks between topic and reference
guides.
Thanks oinopion for the suggestion and jarus for the initial patch.
Backport of 054bdfeff1 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:28>
Django
--------------------------------------+------------------------------------
Reporter: oinopion | Owner: duane9
Type: Cleanup/optimization | Status: closed
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: afraid-to-commit | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by Tim Graham <timograham@…>):
In [changeset:"f0e7a695f5c3723ccf171aefe1b3f0e47c09a28a"]:
{{{
#!CommitTicketReference repository=""
revision="f0e7a695f5c3723ccf171aefe1b3f0e47c09a28a"
[1.7.x] Fixed #17638 -- Added crosslinks between topic and reference
guides.
Thanks oinopion for the suggestion and jarus for the initial patch.
Backport of 054bdfeff1 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/17638#comment:29>