Code

Opened 2 years ago

Last modified 4 months ago

#17638 assigned New feature

Link up topic guides with API reference

Reported by: oinopion Owned by: anonymous
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: internet@… Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
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.

Attachments (0)

Change History (14)

comment:1 Changed 2 years ago by lrekucki

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

Can't hurt.

comment:2 Changed 16 months ago by aaugustin

  • Type changed from Uncategorized to New feature

comment:3 Changed 12 months ago by timo

  • 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 11 months ago by dominicrodger

  • 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 10 months ago by gmohre

  • Owner changed from nobody to gmohre
  • Status changed from new to assigned

comment:6 Changed 10 months 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 10 months ago by gmohre

  • Owner gmohre deleted
  • Status changed from assigned to new

comment:8 Changed 7 months ago by anubhav9042

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

comment:9 Changed 6 months ago by lkitchner

  • Owner set to lkitchner
  • Status changed from new to assigned

comment:10 Changed 4 months ago by kitchnerl

  • Owner lkitchner deleted
  • Status changed from assigned to new

comment:11 Changed 4 months 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 4 months ago by mcintyre1994

  • Owner set to anonymous
  • Status changed from new to assigned

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 4 months ago by mcintyre1994

(Created an account, same mcintyre1994 as above)

comment:14 Changed 4 months ago by timo

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

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as assigned
Next status will be 'assigned'
The ticket will be disowned. Next status will be 'new'
as The resolution will be set. Next status will be 'closed'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.