Re: Polls tutorial suggested mysite/mysite/urls.py improvement

On 27/08/2017 12:45 AM, Derek wrote:
> Mike
>
> Not sure what your github skill level is;

Long ago I once set up  a github repo but lost my certificate when my
laptop died and there it ended. I manage a number of subversion
repositories for a number of people and all my dev is based on svn so I
don't really have the brainspace for git as well. Anyway, git is
probably just a passing fad.

> but have you considered making a clone of the docs
> (https://github.com/django/django/blob/master/docs/), changing that
> page
> (https://github.com/django/django/blob/master/docs/intro/tutorial01.txt)
> and then submitting your changes as a new pull request?

OK - best effort here. I used svn to adjust that file and create a patch
in (I believe) git format. It really needs to be reviewed by a Django
beginner as well as a guru ... see below.

Index: tutorial01.txt
===================================================================
diff --git a/doc/tutorial01.txt b/doc/tutorial01.txt
--- a/doc/tutorial01.txt    (revision 0)
+++ b/doc/tutorial01.txt    (working copy)
@@ -235,7 +235,7 @@
         tests.py
         views.py

-This directory structure will house the poll application.
+This directory structure will house the polls application.

 Write your first view
 =====================
@@ -255,7 +255,7 @@
 This is the simplest view possible in Django. To call the view, we
need to map
 it to a URL - and for this we need a URLconf.

-To create a URLconf in the polls directory, create a file called
``urls.py``.
+To create a URLconf in the polls directory, create a new file called
``urls.py``.
 Your app directory should now look like::

     polls/
@@ -282,10 +282,31 @@
         url(r'^$', views.index, name='index'),
     ]

-The next step is to point the root URLconf at the ``polls.urls`` module. In
-``mysite/urls.py``, add an import for ``django.conf.urls.include`` and
insert
-an :func:`~django.conf.urls.include` in the ``urlpatterns`` list, so
you have:
+The next step is to point the project URLconf at the ``polls.urls`` module.

+.. admonition:: Project urls.py vs. app urls.py vs. views.py
+
+    Your project has a project urls.py file ``mysite/mysite/urls.py``
(Recall
+    that this was automatically created when you issued the command ``$``
+    django-admin startproject mysite). It contains URLconfs. When a browser
+    requests a URL, it needs to trigger some software to make something
happen.
+    Such software is known in Django as a view.
+
+    You have just written your first view in views.py in the polls
application
+    directory. It must be mapped to the outside world via a URLconf.
+
+    While it is possible we don't want to use the project urls.py file,
already
+    mentioned, for all the individual polls app URLs. There might be
many of
+    them. And eventually, the project (or package) may contain many
apps. The
+    polls app really needs its own urls.py for its own URLconfs and we just
+    include them in the project urls.py with a single reference. The
bonus is
+    you can easily re-use the polls app in other projects.
+
+
+In the existing ``mysite/mysite/urls.py``, add an import for
+``django.conf.urls.include`` and insert an
:func:`~django.conf.urls.include` in
+the ``urlpatterns`` list, so you have:
+
 .. snippet::
     :filename: mysite/urls.py



Cheers

Mike






>
> I may be speaking out of turn, as I am not a maintainer; but I am sure
> if you add the above explanation to your submission it will be
> favorably considered.
>
> Derek
>
> On Saturday, 26 August 2017 09:51:51 UTC+2, Mike Dewhirst wrote:
>
> A potential new Django user (a programmer of many decades experience)
> tried Django at my suggestion and struck a problem. Eventually he
> tracked me down and challenged me to prove the problem.
>
> I found the problem and feel that the Polls tutorial docs can be
> easily
> improved.
>
> https://docs.djangoproject.com/en/1.11/intro/tutorial01/
> <https://docs.djangoproject.com/en/1.11/intro/tutorial01/>
>
> In the "Write your first view" section it says ...
>
> The next step is to point the root URLconf at the |polls.urls|
> module.
> In |mysite/urls.py|, add an import for |django.conf.urls.include| and
> insert an |include()|
> <https://docs.djangoproject.com/en/1.11/ref/urls/#django.conf.urls.include
> <https://docs.djangoproject.com/en/1.11/ref/urls/#django.conf.urls.include>>
>
> in the |urlpatterns| list, so you have:
>
> mysite/urls.py
>
> from  django.conf.urls  import  include,  url from django.contrib
> import  admin
>
> urlpatterns  =  [
>       url(r'^polls/',  include('polls.urls')),
>       url(r'^admin/',  admin.site.urls),
> ]
>
>
> The problem is we have two mysite dirs. The docs are helpful in
> suggesting you copy code to paste into urls.py so the focus is on the
> code rather than where to put it. On not finding a urls.py in the
> outer
> mysite dir he created one.
>
> The suggestion for improving the docs here is to change the
> heading line
> above from
>       mysite/urls.py
> to
>       mysite/mysite/urls.py
>
> Alternatively, make a pointed reference to the earlier section in the
> page where startproject created the *inner* mysite dir containing the
> target urls.py. For example, by adding words to the effect that the
> inner mysite/urls.py file will be instrumental in the "hello
> world" step
> later in the tutorial.
>
> Cheers
>
> Mike
>
> --
> You received this message because you are subscribed to the Google
> Groups "Django users" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to django-users+unsubscribe@googlegroups.com
> <mailto:django-users+unsubscribe@googlegroups.com>.
> To post to this group, send email to django-users@googlegroups.com
> <mailto:django-users@googlegroups.com>.
> Visit this group at https://groups.google.com/group/django-users.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/django-users/7ae8d6e4-0760-4441-8a5a-e8bcdd9e0d0c%40googlegroups.com
> <https://groups.google.com/d/msgid/django-users/7ae8d6e4-0760-4441-8a5a-e8bcdd9e0d0c%40googlegroups.com?utm_medium=email&utm_source=footer>.
> For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Django users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to django-users+unsubscribe@googlegroups.com.
To post to this group, send email to django-users@googlegroups.com.
Visit this group at https://groups.google.com/group/django-users.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-users/2a2bef95-a7bf-8250-4e21-0ff16a18ade0%40dewhirst.com.au.
For more options, visit https://groups.google.com/d/optout.