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+unsubscr...@googlegroups.com <mailto:django-users+unsubscr...@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+unsubscr...@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.

Reply via email to