There are some automatically added "[source]" links (see [1] for an example), however, other links don't work (e.g. [2]) because we use the convenience import path in the documentation. It would be a good task to see if this could be fixed in Sphinx.
There is some room to add some "contributor facing" documentation to "internals/" to describe the design of Django's components (e.g. an accepted ticket for doing so for migrations [3]). By the way, here's Jacob's series of blog posts that describes the structure we have: https://jacobian.org/writing/great-documentation/ [1] https://docs.djangoproject.com/en/dev/ref/exceptions/#django.core.exceptions.ObjectDoesNotExist [2] https://docs.djangoproject.com/en/dev/ref/applications/#django.apps.AppConfig [3] https://code.djangoproject.com/ticket/24989 On Monday, December 28, 2015 at 12:40:13 PM UTC-5, Samuel Bishop wrote: > > Broadly speaking, I think the 'optimal' goal is not going to be one that > changes our existing documentation structure in any disruptive way. > > I think the general concept would be covered by either creating a "fourth > division". So we would go from "topics", "reference", and "how-to", to > "topics", "reference", "how-to", and "implementation"/"internals"/"APIs"/etc > Or enhancing the content in the reference section so that in addition to > our existing handwritten documentation, we expose the 'api-docs' tree as an > addendum to the reference section. > > Sphinx gives us a lot of power to work with for trying either approach. I > cant remember which project I saw it on, but I recall seeing some sphinx > powered projects that had Django style hand written documentation, and each > heading (module, class, function, etc) in their hand written documentation > had an automatically generated link to the matcihng "implementation docs" > that took you to that segment of the sphinx autodoc output. It worked quite > well from what I recall. > I'm pretty busy for a few days, but if no one else does this first and > shares some results, I'll definitely take a look at the output from > sphinx's autodoc tools when run over the Django repo and post some > findings. > Since there is certainly the big question of "is the information we have > useful"? > The docstrings and sundry that sphinx uses for autodoc generation may need > work before it measures up to the quality standards of our existing hand > written documentation. > > On Monday, 28 December 2015 06:42:49 UTC+8, Tim Graham wrote: >> >> Adding a survey link is not difficult. We conducted a community survey >> [1] earlier this year with one question related to documentation, "What >> parts of the Django documentation do you find most useful?" What questions >> to ask and how to turn the answers into actionable items is the part I'm >> not sure about and maybe you could advise on. >> >> In my view, Django's docs haven't strayed from the "topics", "reference", >> and "how-to" division that we've had since 1.0 or so. Are you aware of this >> grouping? Maybe a "how the docs are organized" section on the index page >> would help communicate that and make it more intuitive where to look for >> something? >> >> I'll admit I'm skeptical of a wholesale reorganization to this structure >> for several reasons: >> 1. It'll be confusing for existing users who are familiar with the >> current section. >> 2. It'll make it more difficult or impossible to backport documentation >> enhancements to the stable version of the docs (assuming we don't also >> reorganize them with same structure) >> 3. It'll create an opportunity for broken links (obviously we could >> mitigate this to some extent by adding redirects to the new locations). >> >> It seems to me you were pretty close to finding what you were looking for >> at https://docs.djangoproject.com/en/1.9/ref/forms/ (first bullet, I >> think), but I didn't understand what you meant by the page being "the Joy >> of Cooking with Django." >> >> [1] https://www.djangoproject.com/weblog/2015/may/07/community-survey/ >> >> On Sunday, December 27, 2015 at 2:47:35 PM UTC-5, Doug Epling wrote: >>> >>> Again, I am sorry if my comments have ruffled anyone's feathers. I am >>> not going to argue. My sole intent is a positive one. And, indeed, I am >>> humbled by the ongoing work of this community over a period of time that I, >>> until now, have not been involved. >>> >>> I beleive, it is my impression, that between Django 1.1 and now, on the >>> verge of its second major version, there has been a tremendous amount of >>> Python software develpment. And the internal commenting as well as the >>> public documentation has trailed along ad hoc. >>> >>> It can be said without legitimate reproach that any system whether it is >>> thermodynamics or a system of communication, such as our documentation, >>> will naturally tend toward entropy unless something actively intervenes. >>> And we have developed a fairly complex system compared to, say, werksgeud. >>> >>> That patchwork approach has disrupted a flow of utility for users in >>> both public documentation and internal commenting. If this is true, Django >>> has strayed from principles of its foundation. And our motto: "The >>> framework for perfectionists with deadlines."; holds true only until >>> fininding oneself lost in the documentation. >>> >>> Tim is exactly right; this is with no doubt a non-trivial issue. Is >>> Django capable of tackling non-trivial issues? If not I am in the wrong >>> place (a challenge to Django, relax, it's not personal) because I believe >>> Django should be setting the standard. And this issue will not be resolved >>> by an ad hoc approach; meaning our traditional methodology of a problem >>> ticket reporting process is not amenable. This calls for something else if >>> it calls for anything. >>> >>> However, Wim has a good idea! Some exploratory research is a very >>> reasonable first step toward an objective problem definition. Tim, how >>> hard would it be to present every visitor to the documentation with a >>> pop-up (or some other kind of) general invitation to visit a link on Survey >>> Monkey to help us with some feedback? >>> >>> On Friday, December 18, 2015 at 7:02:56 PM UTC-5, Doug Epling wrote: >>>> >>>> I filed bug report >>>> #25952 <https://code.djangoproject.com/ticket/25952>but apparently it >>>> was in the wrong place. And I referenced this post >>>> <https://groups.google.com/forum/#!searchin/django-users/documentation/django-users/1qHviCZMPJA/_8qVb0YYdhAJ>, >>>> >>>> but I was thinking it was this group ... I wonder how that happened? >>>> >>>> So I am hereby suggesting that the road map for the v. 2.0 release >>>> include revamped documentation. >>>> >>>> It should begin as soon as possible with the somewhat standard best >>>> practice of collecting "find what you were looking for" or "was this page >>>> helpful" or "rate this page on its organization, clarity, brevity, etc." >>>> data on every single existing page. >>>> >>>> It might also be helpful to evaluate how different audiences access the >>>> docs. Tutorials are great -- module and class libraries, not so much. >>>> >>>> With resulting user feedback along with expert categorization of >>>> documentation use cases, as with any writing exercise, there must be an >>>> outline. The existing outline might be a good place to start. >>>> >>>> Oh, and those pesky deadlines, when is v. 2.0 slated for release? >>>> >>>> >>>> -- You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group. To unsubscribe from this group and stop receiving emails from it, send an email to django-developers+unsubscr...@googlegroups.com. To post to this group, send email to django-developers@googlegroups.com. Visit this group at https://groups.google.com/group/django-developers. To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/60fb13c7-ace8-4e94-9de2-bb0d78b2c297%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
