Opened 3 years ago

Closed 9 months ago

Last modified 7 months ago

#17238 closed New feature (fixed)

Link to source code in docs

Reported by: santiagobasulto Owned by: nobody
Component: Documentation Version:
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

I think it would be useful to have a link to the source code for each class in the documentation. For example if somebody is looking for the ObjectDoesNotExist exception (https://docs.djangoproject.com/en/1.3/ref/exceptions/#django.core.exceptions.ObjectDoesNotExist), it would be nice to browse the source code.

CakePHP documentation does something similar.

Of course it's possible to get the source code through the package definition, i've done this and found the exception code: https://github.com/django/django/blob/master/django/core/exceptions.py

But with a link would be easier.

Change History (7)

comment:1 Changed 3 years ago by ptone

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

While some references in the docs could be auto linked to the appropriate source code file - many would not. This represents two challenges:

  • going in and finding all the references and making them links/explicit to source location
  • setting the expectation that all future docs efforts follow this standard

I actually have more of an issue with the latter. The docs should not require the source to make sense. If something is not explained well enough to use it without the source, then that is a problem with the docs. Anyone who want to better understand the internals, should develop the skills to quickly find that location in the source.

Lastly, the source browser and docs may not always be available to each other. I build docs locally - and then may move them somewhere for viewing - making links explicit makes the two overly coupled IMO.

I'm leaving this as unreviewed, as I feel my solo opinion is not enough to warrant a close.

comment:2 Changed 3 years ago by aaugustin

  • Triage Stage changed from Unreviewed to Design decision needed

Sphinx has an extension to support this: http://sphinx.pocoo.org/ext/viewcode.html

I don't know if the website would support it out of the box. If it does, we could enable this extension.

Marking as DDN because this needs some testing before we commit to implementing it.

comment:3 Changed 3 years ago by aaugustin

  • Triage Stage changed from Design decision needed to Accepted

In fact, this ticket should be "Accepted", because the idea is worth exploring.

comment:4 Changed 2 years ago by pydanny

When I did this for the refactored CBV docs in June of 2012, @jacobian said he didn't want this feature and had me take out the direct code references. He said it made the documentation much harder to maintain.

comment:5 Changed 9 months ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from new to closed

In 9ed4a8c6b1a552a03fd27b77f1b742e3f9c66bde:

Fixed #17238 -- Added source code links to docs using sphinx.ext.viewcode.

Thanks santiagobasulto for the suggestion.

comment:6 Changed 7 months ago by Tim Graham <timograham@…>

In 477ab02312d47969bdfd7c1616da27379bb1b967:

[1.6.x] Fixed #17238 -- Added source code links to docs using sphinx.ext.viewcode.

Thanks santiagobasulto for the suggestion.

Backport of 9ed4a8c6b1 from master

comment:7 Changed 7 months ago by Tim Graham <timograham@…>

In dc9751a6e7009290b1515934ccf771e2306aa4ab:

[1.7.x] Fixed #17238 -- Added source code links to docs using sphinx.ext.viewcode.

Thanks santiagobasulto for the suggestion.

Backport of 9ed4a8c6b1 from master

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