Opened 5 years ago

Closed 2 years ago

Last modified 2 years ago

#17638 closed Cleanup/optimization (fixed)

Link up topic guides with API reference

Reported by: Tomek Paczkowski Owned by: Duane Hilton
Component: Documentation Version: master
Severity: Normal Keywords: afraid-to-commit
Cc: internet@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: yes UI/UX: no

Description

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.

Change History (29)

comment:1 Changed 5 years ago by Łukasz Rekucki

Needs documentation: unset
Needs tests: unset
Patch needs improvement: unset
Triage Stage: UnreviewedAccepted

Can't hurt.

comment:2 Changed 4 years ago by Aymeric Augustin

Type: UncategorizedNew feature

comment:3 Changed 3 years ago by Tim Graham

Easy pickings: set

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.

comment:4 Changed 3 years ago by Dominic Rodger

Cc: internet@… added

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.

comment:5 Changed 3 years ago by gmohre

Owner: changed from nobody to gmohre
Status: newassigned

comment:6 Changed 3 years ago 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

comment:7 Changed 3 years ago by gmohre

Owner: gmohre deleted
Status: assignednew

comment:8 Changed 3 years ago by ANUBHAV JOSHI

I think the proposed thing could be explained in a more better way.

comment:9 Changed 3 years ago by lkitchner

Owner: set to lkitchner
Status: newassigned

comment:10 Changed 3 years ago by kitchnerl

Owner: lkitchner deleted
Status: assignednew

comment:11 Changed 3 years ago 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 class based views introductory material (current) and class based views API reference (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.

comment:12 Changed 3 years ago by mcintyre1994

Owner: set to anonymous
Status: newassigned

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!

comment:13 Changed 3 years ago by mcintyre1994

(Created an account, same mcintyre1994 as above)

comment:14 Changed 3 years ago by Tim Graham

I don't think the table of contents should be moved into the "See Also" boxes, otherwise, this looks ok.

comment:15 Changed 2 years ago by Christoph Heer

Owner: changed from anonymous to Christoph Heer
Type: New featureCleanup/optimization

There was no action since 4 months, I hope it's okay that I adopt this ticket.

comment:16 Changed 2 years ago by Christoph Heer

See also #23106

comment:17 Changed 2 years ago by Christoph Heer

Has patch: set

comment:18 Changed 2 years ago by Tim Graham

Patch needs improvement: set

The idea was to do this for all pages that have both topic and ref docs, not just for class based views.

comment:19 Changed 2 years ago by Christoph Heer

I added a few more links between pages which make sense in my eyes.

comment:20 Changed 2 years ago by Tim Graham

Patch needs improvement: unset

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.

comment:21 Changed 2 years ago by merb

Patch needs improvement: set

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 ;))

comment:22 Changed 2 years ago by Tim Graham

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

comment:23 Changed 2 years ago by Tim Graham

Owner: Christoph Heer deleted
Status: assignednew

Someone else is welcome to pick where jarus left off.

comment:24 Changed 2 years ago by Daniele Procida

Keywords: afraid-to-commit added

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.

comment:25 Changed 2 years ago by Duane Hilton

Owner: set to Duane Hilton
Status: newassigned

comment:26 Changed 2 years ago by Duane Hilton

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, ref/migration-operations, and ref/templates/index that go to the corresponding topics pages. https://github.com/django/django/pull/3285

Last edited 2 years ago by Duane Hilton (previous) (diff)

comment:27 Changed 2 years ago by Tim Graham <timograham@…>

Resolution: fixed
Status: assignedclosed

In 054bdfeff113459a48974d08098915431d0a093d:

Fixed #17638 -- Added crosslinks between topic and reference guides.

Thanks oinopion for the suggestion and jarus for the initial patch.

comment:28 Changed 2 years ago by Tim Graham <timograham@…>

In 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

comment:29 Changed 2 years ago by Tim Graham <timograham@…>

In 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

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