Polls tutorial suggested mysite/mysite/urls.py improvement

[Mike Dewhirst]

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/

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>
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

[Jim Fuqua]

I agree.  Anyone experienced in Django would not be confused.  I have been away from Python for over ten years and totally new to Django.  There are a number of such issues in the tutorial that got me "off track".   

A useful feature for the total novice would be a link to a folder with a correct copy of all "mysite" files at the end of each section.  If the novice fails to include a file or made some other simple mistake they could get back "on track".  I did not get "off track" on this one but I did on several others. They were careless mistakes, but for a novice, the only way out is usually to completely start over.

The tutorial says "When starting your first real project, however, you may want to use a more scalable database like PostgreSQL, to avoid database-switching headaches down the road.". That is an invitation to the novice to simultaneously take a much more complex path.  A link to some basic PostgreSQL issues like how to drop the "mysite" PostgresSQL database and start over would be helpful.  With sqlite3 it is easy to erase everything and start over.  With Postgres, the changes to the database are not so easily undone. I finally figured out how to change the "mysite" user and drop the database, but it was not easy. A simple "DROP DATABASE "mysite"; does not do the job without changing the database owner and killing other users of the database before dropping the database.

Simple UX comments from novices concerning the Tutorial could make the life of those who follow much easier.  No expert is a good UX judge of any tutorial from the perspective of a novice.

jimfuqua

[Derek]

Mike

Not sure what your github skill level is; 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?

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

[Mike Dewhirst]

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

> --
> 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...@googlegroups.com
> <mailto:django-users...@googlegroups.com>.
> To post to this group, send email to django...@googlegroups.com
> <mailto:django...@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.