[Django] #17238: Link to source code in docs

6 views
Skip to first unread message

Django

unread,
Nov 16, 2011, 7:04:34 AM11/16/11
to django-...@googlegroups.com
#17238: Link to source code in docs
---------------------------------+--------------------
Reporter: santiagobasulto | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version:
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
---------------------------------+--------------------
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.

--
Ticket URL: <https://code.djangoproject.com/ticket/17238>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

Django

unread,
Nov 17, 2011, 4:55:29 PM11/17/11
to django-...@googlegroups.com
#17238: Link to source code in docs
---------------------------------+--------------------------------------
Reporter: santiagobasulto | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version:
Severity: Normal | Resolution:
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
---------------------------------+--------------------------------------
Changes (by ptone):

* needs_better_patch: => 0
* needs_tests: => 0
* needs_docs: => 0


Comment:

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.

--
Ticket URL: <https://code.djangoproject.com/ticket/17238#comment:1>

Django

unread,
Nov 18, 2011, 2:13:17 AM11/18/11
to django-...@googlegroups.com
#17238: Link to source code in docs
-------------------------------------+-------------------------------------
Reporter: santiagobasulto | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version:
Severity: Normal | Resolution:
Keywords: | Triage Stage: Design
Has patch: 0 | decision needed
Needs tests: 0 | Needs documentation: 0
Easy pickings: 0 | Patch needs improvement: 0
| UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by aaugustin):

* stage: Unreviewed => Design decision needed


Comment:

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.

--
Ticket URL: <https://code.djangoproject.com/ticket/17238#comment:2>

Django

unread,
Dec 11, 2011, 6:49:48 AM12/11/11
to django-...@googlegroups.com
#17238: Link to source code in docs
---------------------------------+------------------------------------
Reporter: santiagobasulto | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version:
Severity: Normal | Resolution:
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 aaugustin):

* stage: Design decision needed => Accepted


Comment:

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

--
Ticket URL: <https://code.djangoproject.com/ticket/17238#comment:3>

Django

unread,
Nov 8, 2012, 8:33:16 PM11/8/12
to django-...@googlegroups.com
#17238: Link to source code in docs
---------------------------------+------------------------------------

Reporter: santiagobasulto | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version:
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
---------------------------------+------------------------------------

Comment (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.

--
Ticket URL: <https://code.djangoproject.com/ticket/17238#comment:4>

Django

unread,
Jun 7, 2014, 8:56:26 AM6/7/14
to django-...@googlegroups.com
#17238: Link to source code in docs
---------------------------------+------------------------------------
Reporter: santiagobasulto | Owner: nobody
Type: New feature | Status: closed
Component: Documentation | Version:
Severity: Normal | Resolution: fixed

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 Tim Graham <timograham@…>):

* status: new => closed
* resolution: => fixed


Comment:

In [changeset:"9ed4a8c6b1a552a03fd27b77f1b742e3f9c66bde"]:
{{{
#!CommitTicketReference repository=""
revision="9ed4a8c6b1a552a03fd27b77f1b742e3f9c66bde"
Fixed #17238 -- Added source code links to docs using sphinx.ext.viewcode.

Thanks santiagobasulto for the suggestion.
}}}

--
Ticket URL: <https://code.djangoproject.com/ticket/17238#comment:5>

Django

unread,
Aug 19, 2014, 5:46:06 PM8/19/14
to django-...@googlegroups.com
#17238: Link to source code in docs
---------------------------------+------------------------------------
Reporter: santiagobasulto | Owner: nobody
Type: New feature | Status: closed
Component: Documentation | Version:

Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
---------------------------------+------------------------------------

Comment (by Tim Graham <timograham@…>):

In [changeset:"477ab02312d47969bdfd7c1616da27379bb1b967"]:
{{{
#!CommitTicketReference repository=""
revision="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
}}}

--
Ticket URL: <https://code.djangoproject.com/ticket/17238#comment:6>

Django

unread,
Aug 19, 2014, 5:46:07 PM8/19/14
to django-...@googlegroups.com
#17238: Link to source code in docs
---------------------------------+------------------------------------
Reporter: santiagobasulto | Owner: nobody
Type: New feature | Status: closed
Component: Documentation | Version:

Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
---------------------------------+------------------------------------

Comment (by Tim Graham <timograham@…>):

In [changeset:"dc9751a6e7009290b1515934ccf771e2306aa4ab"]:
{{{
#!CommitTicketReference repository=""
revision="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
}}}

--
Ticket URL: <https://code.djangoproject.com/ticket/17238#comment:7>

Reply all
Reply to author
Forward
0 new messages