Re: Help needed with the MySQL max index length problem for Django 1.10

[Aymeric Augustin]

At that point, I'd prefer picking an arbitrary length that makes sense for
the underlying data rather than one based on MySQL's current limitations.

Name length sounds like an reasonable proxy for username length. A quick
Google search turns up
http://www.historyrundown.com/top-5-people-with-the-longest-names/

If we skip the pathological cases — e.g. people with one name per letter of
the alphabet — the first sensible name in that list is Picasso with 122
characters: "Pablo Diego José Francisco de Paula Juan Nepomuceno María de
los Remedios Cipriano de la Santísima Trinidad Ruiz y Picasso"

The original ticket, #20846, discussed a length between 75 and 150.

The argument for 254 was "email as username". In that case, Django's native
User with distinct username and email fields isn't appropriate. A custom
user model storing the the username/email in a unique EmailField is better.
MySQL users can specify the appropriate max_length — which we should
document — there.

I'd jut give username max_length=120. (Sorry, Picasso.)

-- 
Aymeric.


2015-12-28 23:49 GMT+01:00 Tim Graham :

> Ugh, I guess I'm in favor of max_length=191. It'll just be awkward to
> explain that one in the docs.
>
> On Monday, December 28, 2015 at 3:27:23 PM UTC-5, Collin Anderson wrote:
>>
>> Hi All,
>>
>> I finally looked at this more today. I started working on the INDEX
>> (col1(191)) solution from #18392, but unfortunately I don't think we can
>> use that solution in this case because it's a UNIQUE index. (I still think
>> it's best solution for non-unique indexes.)
>>
>> I think these are our options (in my humble order of preference), none of
>> them ideal:
>> 1. Make username max_length=191 or some other nice number less 191.
>> 2. Revert completely back to username max_length=30
>> 3. Tell mysql folks they can only use the insecure[1] version of utf8
>> unless do some really complex reconfiguration (see "Hardest" solution in
>> the article [2]) to get utfmb4 support. Based on the fact that they're
>> using mysql and not PostgreSQL in the first place, many mysql users are
>> probably are unable to make the needed changes.
>>
>> The good news is that mysql 5.7.7 (which, will _start_ to get a lot of
>> real use in 16.04) changes some defaults[3] to make the "hardest" solution
>> easier (just need to set ROW_FORMAT=DYNAMIC). MariaDB hasn't changed the
>> default [4]. I hope they do before RHEL/CentOS 8. Even then it's a long
>> wait before most people have it.
>>
>> Collin
>>
>> [1] https://youtu.be/qFfjJ8pOrWY?t=2534
>> [2] https://serversforhackers.com/mysql-utf8-and-indexing
>> [3] http://bugs.mysql.com/bug.php?id=68453#c430229
>> [4]
>> https://mariadb.com/kb/en/mariadb/xtradbinnodb-server-system-variables/#innodb_large_prefix
>>
>>
>>
>> On Mon, Dec 21, 2015 at 11:32 AM, Tim Graham  wrote:
>>
>>> I merged the often requested increase of User.username max_length to 254
>>> characters [1] a few weeks ago, however, the ticket was reopened pointing
>>> out this issue:
>>>
>>>
>>> "This patch breaks on MySQL installations using the utf8mb4 charset,
>>> because it breaks the index length limit - it comes out at a maximum of 254
>>> * 4 = 1016 bytes whilst by default InnoDB can only index 767 bytes. I found
>>> this because I am using utf8mb4 in django-mysql's tests.
>>>
>>> Django encourages using the utf8 charset (3 bytes per character - cannot
>>> store emojis), although there has been some discussion for moving to
>>> utf8mb4 in #18392 . One
>>> can index 254 character utf8mb4 fields in MySQL by using a couple settings
>>> as described in that ticket, Django could enforce those, or the field could
>>> be changed to just 191 characters instead which is the maximum indexable 
>>> (767
>>> // 4)."
>>>
>>> Do we have any MySQL enthusiasts willing to champion a patch (or at
>>> least a decision design about the best way to proceed) for #18392 [2] to
>>> resolve this?
>>>
>>> [1] https://code.djangoproject.com/ticket/20846
>>> [2] https://code.djangoproject.com/ticket/18392
>>>
>>> --
>>> 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-develop...@googlegroups.com.
>>> To post to this group, send email to django-d...@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/ceb190b5-5218-446c-a6a0-0aea75e7fd6b%40googlegroups.com
>>> 
>>> .
>>> For more options, visit https://groups.google.com/d/optout.
>>>
>>
>> --
> You received this message because you are subscribed to the Google Groups
> "Django developers (Contributions to Django 

Re: structural & functional review of django documentation

[Tim Graham]

I've refined Daniele's explanation here: 
https://github.com/django/django/pull/5888

Let me know if it helps and what could be better.

On Monday, December 28, 2015 at 11:31:30 PM UTC-5, Eric Holscher wrote:
>
>
>
> On Monday, December 28, 2015 at 4:52:36 PM UTC-8, Daniele Procida wrote:
>>
>> On Mon, Dec 28, 2015, Samuel Bishop  wrote:
>> The main existing sections are: 
>>
>> * tutorials (/intro) 
>>
>> Tutorials take the new user by the hand through a series of steps. The 
>> important thing isn't to explain all the steps, but to achieve something 
>> useful with a minimum of effort. 
>>
>> After every step of a tutorial, the user should have something that 
>> works, even if they barely understand what is happening (and it's not 
>> necessary for them to understand, that can come later. What matters is that 
>> they are successful). 
>>
>> * how-to guides (/howto) 
>>
>> How-to guides are recipes that take the user through steps in key 
>> subjects. They are more advanced than tutorials and assume a lot more about 
>> what the user already knows than tutorials do, and unlike documents in the 
>> tutorial they can stand alone.   
>>
>> * discussion and explanation (/topic) 
>>
>> Aimed at explaining (at a fairly high level) rather than doing. 
>>
>> * reference (/ref) 
>>
>> Technical reference for APIs, key models and so on. It doesn't need to 
>> explain so much as describe and instruct. 
>>
>>  
> I think the above post does a good job of describing the layout, and 
> something similar should be included in the docs. Without having read 
> Jacob's posts on the subject, there is nothing in the official docs that 
> gives the reader an understanding that this is how things are laid out, as 
> far as I know.
>
> I think the underlying structure makes sense, and it seems that mostly 
> people are just upset about the lack of a pure auto-generated code 
> reference. I believe historically that this has been excluded explicitly, 
> not because of lack of technology. There is no use of autodoc in the Django 
> tree, even where it might make sense.
>
> At Django Under the Hood this year, I had a few conversations with folks 
> about rethinking and explicitly defining these policies. I think it makes a 
> lot of sense to write down the logic and structure behind these decisions 
> in a DEP, and explain the layout to doc users in a few places in the 
> documentation explicitly.
>
> Cheers,
> Eric 
>

-- 
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/9fa508d3-6dcc-4fd1-88c7-51845e0a00cb%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: delegating our static file serving

[David Evans]

I'd be very happy to help with this. Two things to mention:

1. When I first wrote WhiteNoise the FileResponse class didn't exist and so 
the only way I could access `wsgi.file_wrapper` was by wrapping the wsgi 
application directly and bypassing Django. Now we have the FileResponse 
class it would be possible to implement WhiteNoise as standard Django 
middleware without having to edit wsgi.py. I think this would be a much 
cleaner approach, and I don't think it will be too much work to implement. 
I should have time to look at this next week.

2. Serving media files is a slightly different case. WhiteNoise was 
designed around the assumption that it's serving a set of 
developer-supplied, public files which remain unchanged during the lifetime 
of the process. This simplifies a lot of performance and security concerns 
that come with serving mutable, user-supplied files. At present, if you use 
`add_files(settings.MEDIA_ROOT, prefix=settings.MEDIA_URL)` as you 
suggested then WhiteNoise won't pick up any files that were uploaded after 
the application was started -- at least, not unless you enable the 
"autorefresh" setting which I explicitly don't recommend for production.

Obviously it's possible to support this if we decide this is an important 
goal but it will need more thought and will definitely be more work than 
just supporting static files.

On Tuesday, 29 December 2015 00:36:06 UTC, Tim Graham wrote:
>
> I'd like to work together with Dave to develop a proof of concept that 
> integrates whitenoise into Django. I spent about an hour looking through 
> whitenoise and our own static file serving code, and I think integrating 
> whitenoise will yield a simpler user experience with about the same amount 
> of code as have now.
>
> Essentially, we'd recommend adding something like this to existing wsgi.py 
> files (it would be in the default startproject template)
>
> from whitenoise.django import DjangoWhiteNoise
> application = DjangoWhiteNoise(application)
> application.add_files(settings.MEDIA_ROOT, prefix=settings.MEDIA_URL)
>
> which would have the benefit of working out of the box in production too, 
> I think. Of course, you could disable that based on settings.DEBUG or some 
> other toggle.
>
> We could then deprecate:
>
> * django/contrib/staticfiles/views.py
> * django/contrib/staticfiles/management/commands/runserver.py
> * django/contrib/staticfiles/handlers.py
> * django/views/static.py
>
> Any objections to doing further investigation in this area?
>
> On Saturday, June 20, 2015 at 8:09:11 AM UTC-4, David Evans wrote:
>>
>> On Friday, 5 December 2014 19:14:29 UTC, Carl Meyer wrote:
>>>
>>> On 12/04/2014 10:33 PM, Collin Anderson wrote: 
>>> > Hi All, 
>>> > 
>>> > I'm pretty interested in getting secure and _somewhat_ efficient 
>>> static 
>>> > file serving in Django. 
>>> > 
>>> > Quick history: 
>>> > 2005 - Jacob commits #428: a "static pages" view.  Note that this view 
>>> > should only be used for testing!" 
>>> > 2010 - Jannis adds staticfiles. Serving via django is considered 
>>> "grossly 
>>> > inefficient and probably insecure". 
>>> > 2011 - Graham Dumpleton adds wsgi.file_wrapper to Gunicorn. 
>>> > 2012 - Aymeric adds StreamingHttpResponse and now files are read in 
>>> chunks 
>>> > rather than reading the entire file into memory. (No longer grossly 
>>> > inefficient IMHO.) 
>>> > 
>>> > I propose: 
>>> > - Deprecate the "show_indexes" parameter of static.serve() (unless 
>>> people 
>>> > actually use it). 
>>> > - Have people report security issues to secu...@djangoproject.com 
>>> (like 
>>> > always) 
>>> > - Audit the code and possibly add more security checks and tests. 
>>> > - add wsgi.file_wrapper support to responses (5-line proof of concept: 
>>> > https://github.com/django/django/pull/3650 ) 
>>> > - support serving static files in production, but still recommend 
>>> > nginx/apache or a cdn for performance. 
>>> > - make serving static files in production an opt-in, but put the view 
>>> in 
>>> > project_template/project_name/urls.py 
>>> > 
>>> > I think it's a huge win for low-traffic sites or sites in the "just 
>>> trying 
>>> > to deploy and get something live" phase. You can always optimize later 
>>> by 
>>> > serving via nginx or cdn. 
>>> > We already have the views, api, and logic around for finding and 
>>> serving 
>>> > the correct files. 
>>> > We can be just as efficient and secure as static/dj-static without 
>>> needing 
>>> > to make people install and configure wsgi middleware to the 
>>> application. 
>>> > We could have staticfiles classes implement more complicated features 
>>> like 
>>> > giving cache recommendations, and serving pre-gzipped files. 
>>> > 
>>> > Is this a good idea? I realize it's not totally thought through. I'm 
>>> fine 
>>> > with waiting until 1.9 if needed. 
>>>
>>> I also think this is a good plan. It certainly makes sense to look at 
>>> "static" and "whitenoise" for ideas and compare their code to ours 

Re: FK constraints are not checked at the end of nested atomic blocks

[Gavin Wahl]

What does it even mean for constraints to be checked at savepoint commit? I 
would expect this to not cause any errors:

with atomic():
# insert invalid fk
with atomic(check_deferred_constraints=True):
# do stuff that doesn't invalidate any contraints
# delete the invalid fk inserted before

But with the proposed solution _all_ constraints are checked, not just the 
ones invalidated in that savepoint.

-- 
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/a7f4acf5-3a06-4b5f-adb2-ff025f5511a1%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Help needed with the MySQL max index length problem for Django 1.10

[Collin Anderson]

I propose 150 to err on the longer 
side: https://github.com/django/django/pull/5891

On Tuesday, December 29, 2015 at 5:28:01 AM UTC-5, Aymeric Augustin wrote:
>
> At that point, I'd prefer picking an arbitrary length that makes sense for 
> the underlying data rather than one based on MySQL's current limitations.
>
> Name length sounds like an reasonable proxy for username length. A quick 
> Google search turns up 
> http://www.historyrundown.com/top-5-people-with-the-longest-names/
>
> If we skip the pathological cases — e.g. people with one name per letter 
> of the alphabet — the first sensible name in that list is Picasso with 122 
> characters: "Pablo Diego José Francisco de Paula Juan Nepomuceno María de 
> los Remedios Cipriano de la Santísima Trinidad Ruiz y Picasso"
>
> The original ticket, #20846, discussed a length between 75 and 150.
>
> The argument for 254 was "email as username". In that case, Django's 
> native User with distinct username and email fields isn't appropriate. A 
> custom user model storing the the username/email in a unique EmailField is 
> better. MySQL users can specify the appropriate max_length — which we 
> should document — there.
>
> I'd jut give username max_length=120. (Sorry, Picasso.)
>
> -- 
> Aymeric.
>
>
> 2015-12-28 23:49 GMT+01:00 Tim Graham >:
>
>> Ugh, I guess I'm in favor of max_length=191. It'll just be awkward to 
>> explain that one in the docs.
>>
>> On Monday, December 28, 2015 at 3:27:23 PM UTC-5, Collin Anderson wrote:
>>>
>>> Hi All,
>>>
>>> I finally looked at this more today. I started working on the INDEX 
>>> (col1(191)) solution from #18392, but unfortunately I don't think we can 
>>> use that solution in this case because it's a UNIQUE index. (I still think 
>>> it's best solution for non-unique indexes.)
>>>
>>> I think these are our options (in my humble order of preference), none 
>>> of them ideal:
>>> 1. Make username max_length=191 or some other nice number less 191.
>>> 2. Revert completely back to username max_length=30
>>> 3. Tell mysql folks they can only use the insecure[1] version of utf8 
>>> unless do some really complex reconfiguration (see "Hardest" solution in 
>>> the article [2]) to get utfmb4 support. Based on the fact that they're 
>>> using mysql and not PostgreSQL in the first place, many mysql users are 
>>> probably are unable to make the needed changes.
>>>
>>> The good news is that mysql 5.7.7 (which, will _start_ to get a lot of 
>>> real use in 16.04) changes some defaults[3] to make the "hardest" solution 
>>> easier (just need to set ROW_FORMAT=DYNAMIC). MariaDB hasn't changed the 
>>> default [4]. I hope they do before RHEL/CentOS 8. Even then it's a long 
>>> wait before most people have it.
>>>
>>> Collin
>>>
>>> [1] https://youtu.be/qFfjJ8pOrWY?t=2534
>>> [2] https://serversforhackers.com/mysql-utf8-and-indexing
>>> [3] http://bugs.mysql.com/bug.php?id=68453#c430229
>>> [4] 
>>> https://mariadb.com/kb/en/mariadb/xtradbinnodb-server-system-variables/#innodb_large_prefix
>>>
>>>
>>>
>>> On Mon, Dec 21, 2015 at 11:32 AM, Tim Graham  wrote:
>>>
 I merged the often requested increase of User.username max_length to 
 254 characters [1] a few weeks ago, however, the ticket was reopened 
 pointing out this issue:


 "This patch breaks on MySQL installations using the utf8mb4 charset, 
 because it breaks the index length limit - it comes out at a maximum of 
 254 
 * 4 = 1016 bytes whilst by default InnoDB can only index 767 bytes. I 
 found 
 this because I am using utf8mb4 in django-mysql's tests.

 Django encourages using the utf8 charset (3 bytes per character - 
 cannot store emojis), although there has been some discussion for moving 
 to 
 utf8mb4 in #18392 . One 
 can index 254 character utf8mb4 fields in MySQL by using a couple settings 
 as described in that ticket, Django could enforce those, or the field 
 could 
 be changed to just 191 characters instead which is the maximum indexable 
 (767 
 // 4)."

 Do we have any MySQL enthusiasts willing to champion a patch (or at 
 least a decision design about the best way to proceed) for #18392 [2] to 
 resolve this? 

 [1] https://code.djangoproject.com/ticket/20846
 [2] https://code.djangoproject.com/ticket/18392

 -- 
 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-develop...@googlegroups.com.
 To post to this group, send email to django-d...@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/ceb190b5-5218-446c-a6a0-0aea75e7fd6b%40googlegroups.com
>>

Re: Help needed with the MySQL max index length problem for Django 1.10

[Collin Anderson]

Though wouldn't mind 180 either.

On Tue, Dec 29, 2015 at 2:55 PM, Collin Anderson 
wrote:

> I propose 150 to err on the longer side:
> https://github.com/django/django/pull/5891
>
> On Tuesday, December 29, 2015 at 5:28:01 AM UTC-5, Aymeric Augustin wrote:
>>
>> At that point, I'd prefer picking an arbitrary length that makes sense
>> for the underlying data rather than one based on MySQL's current
>> limitations.
>>
>> Name length sounds like an reasonable proxy for username length. A quick
>> Google search turns up
>> http://www.historyrundown.com/top-5-people-with-the-longest-names/
>>
>> If we skip the pathological cases — e.g. people with one name per letter
>> of the alphabet — the first sensible name in that list is Picasso with 122
>> characters: "Pablo Diego José Francisco de Paula Juan Nepomuceno María de
>> los Remedios Cipriano de la Santísima Trinidad Ruiz y Picasso"
>>
>> The original ticket, #20846, discussed a length between 75 and 150.
>>
>> The argument for 254 was "email as username". In that case, Django's
>> native User with distinct username and email fields isn't appropriate. A
>> custom user model storing the the username/email in a unique EmailField is
>> better. MySQL users can specify the appropriate max_length — which we
>> should document — there.
>>
>> I'd jut give username max_length=120. (Sorry, Picasso.)
>>
>> --
>> Aymeric.
>>
>>
>> 2015-12-28 23:49 GMT+01:00 Tim Graham :
>>
>>> Ugh, I guess I'm in favor of max_length=191. It'll just be awkward to
>>> explain that one in the docs.
>>>
>>> On Monday, December 28, 2015 at 3:27:23 PM UTC-5, Collin Anderson wrote:

 Hi All,

 I finally looked at this more today. I started working on the INDEX
 (col1(191)) solution from #18392, but unfortunately I don't think we can
 use that solution in this case because it's a UNIQUE index. (I still think
 it's best solution for non-unique indexes.)

 I think these are our options (in my humble order of preference), none
 of them ideal:
 1. Make username max_length=191 or some other nice number less 191.
 2. Revert completely back to username max_length=30
 3. Tell mysql folks they can only use the insecure[1] version of utf8
 unless do some really complex reconfiguration (see "Hardest" solution in
 the article [2]) to get utfmb4 support. Based on the fact that they're
 using mysql and not PostgreSQL in the first place, many mysql users are
 probably are unable to make the needed changes.

 The good news is that mysql 5.7.7 (which, will _start_ to get a lot of
 real use in 16.04) changes some defaults[3] to make the "hardest" solution
 easier (just need to set ROW_FORMAT=DYNAMIC). MariaDB hasn't changed the
 default [4]. I hope they do before RHEL/CentOS 8. Even then it's a long
 wait before most people have it.

 Collin

 [1] https://youtu.be/qFfjJ8pOrWY?t=2534
 [2] https://serversforhackers.com/mysql-utf8-and-indexing
 [3] http://bugs.mysql.com/bug.php?id=68453#c430229
 [4]
 https://mariadb.com/kb/en/mariadb/xtradbinnodb-server-system-variables/#innodb_large_prefix



 On Mon, Dec 21, 2015 at 11:32 AM, Tim Graham 
 wrote:

> I merged the often requested increase of User.username max_length to
> 254 characters [1] a few weeks ago, however, the ticket was reopened
> pointing out this issue:
>
>
> "This patch breaks on MySQL installations using the utf8mb4 charset,
> because it breaks the index length limit - it comes out at a maximum of 
> 254
> * 4 = 1016 bytes whilst by default InnoDB can only index 767 bytes. I 
> found
> this because I am using utf8mb4 in django-mysql's tests.
>
> Django encourages using the utf8 charset (3 bytes per character -
> cannot store emojis), although there has been some discussion for moving 
> to
> utf8mb4 in #18392 . One
> can index 254 character utf8mb4 fields in MySQL by using a couple settings
> as described in that ticket, Django could enforce those, or the field 
> could
> be changed to just 191 characters instead which is the maximum indexable 
> (767
> // 4)."
>
> Do we have any MySQL enthusiasts willing to champion a patch (or at
> least a decision design about the best way to proceed) for #18392 [2] to
> resolve this?
>
> [1] https://code.djangoproject.com/ticket/20846
> [2] https://code.djangoproject.com/ticket/18392
>
> --
> 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-develop...@googlegroups.com.
> To post to this group, send email to django-d...@googlegroups.com.
> Visit this group at https://groups.google.com/group/django-devel

Re: structural & functional review of django documentation

[Tim Allen]

Tim: that's definitely a big help, but still a click away. I'm just 
brainstorming here, please bear with me!

I think part of my confusion as a newbie is from the front page itself, 
at https://docs.djangoproject.com/

Now that I understand the concepts behind the documentation better (thanks 
Daniele), it doesn't appear to be very well reflected on the front page. 
There is a list of First steps, The model layer, and so on, but nothing in 
the interface that clearly lets the user know that the documentation is 
meant to be broken down into the "Tutorials / How-To / Explanation & 
Discussion / Reference" paradigm. If that's what we are trying to 
communicate, it should be shown to the user from the front of the 
documentation clearly, IMHO.

A top-down, browsable hierarchy would have been extremely useful to me when 
I was just getting started. The ToC has the kind of hierarchy I'm referring 
to (https://docs.djangoproject.com/en/1.9/contents/), but comes across to 
the user as a wall of text / links. Perhaps developing the ToC into a 
navigation menu is worth some effort?

Does anyone else feel there is far too much on the front page? An 
experienced Django dev will be more comfortable finding what they need 
within the documentation, am I alone in thinking a much more simple front 
page might be useful to the newcomer?

Regards,

Tim

On Tuesday, December 29, 2015 at 11:25:40 AM UTC-5, Tim Graham wrote:
>
> I've refined Daniele's explanation here: 
> https://github.com/django/django/pull/5888
>
> Let me know if it helps and what could be better.
>
> On Monday, December 28, 2015 at 11:31:30 PM UTC-5, Eric Holscher wrote:
>>
>>
>>
>> On Monday, December 28, 2015 at 4:52:36 PM UTC-8, Daniele Procida wrote:
>>>
>>> On Mon, Dec 28, 2015, Samuel Bishop  wrote:
>>> The main existing sections are: 
>>>
>>> * tutorials (/intro) 
>>>
>>> Tutorials take the new user by the hand through a series of steps. The 
>>> important thing isn't to explain all the steps, but to achieve something 
>>> useful with a minimum of effort. 
>>>
>>> After every step of a tutorial, the user should have something that 
>>> works, even if they barely understand what is happening (and it's not 
>>> necessary for them to understand, that can come later. What matters is that 
>>> they are successful). 
>>>
>>> * how-to guides (/howto) 
>>>
>>> How-to guides are recipes that take the user through steps in key 
>>> subjects. They are more advanced than tutorials and assume a lot more about 
>>> what the user already knows than tutorials do, and unlike documents in the 
>>> tutorial they can stand alone.   
>>>
>>> * discussion and explanation (/topic) 
>>>
>>> Aimed at explaining (at a fairly high level) rather than doing. 
>>>
>>> * reference (/ref) 
>>>
>>> Technical reference for APIs, key models and so on. It doesn't need to 
>>> explain so much as describe and instruct. 
>>>
>>>  
>> I think the above post does a good job of describing the layout, and 
>> something similar should be included in the docs. Without having read 
>> Jacob's posts on the subject, there is nothing in the official docs that 
>> gives the reader an understanding that this is how things are laid out, as 
>> far as I know.
>>
>> I think the underlying structure makes sense, and it seems that mostly 
>> people are just upset about the lack of a pure auto-generated code 
>> reference. I believe historically that this has been excluded explicitly, 
>> not because of lack of technology. There is no use of autodoc in the Django 
>> tree, even where it might make sense.
>>
>> At Django Under the Hood this year, I had a few conversations with folks 
>> about rethinking and explicitly defining these policies. I think it makes a 
>> lot of sense to write down the logic and structure behind these decisions 
>> in a DEP, and explain the layout to doc users in a few places in the 
>> documentation explicitly.
>>
>> Cheers,
>> Eric 
>>
>

-- 
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/12221065-6358-4a20-a383-60f3aac5f240%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Tim Graham]

The docs I proposed would be added to the front page. I'm not sure if I 
misunderstand what you meant by "still a click away"?

To me, the front page is a topical guide that links to all documentation 
pages (topics/ref/howto) for each topic. I think it's useful, though I 
don't really use it myself since I have most of the URLs in my history, so 
I just rely on autocomplete to find the page I'm looking for. ;-)

Turning the table of contents page into a CSS menu sounds like a possibly 
worthwhile task.

There is also an idea here for adding navigation breadcrumbs to the 
documentation which might help:
https://github.com/django/djangoproject.com/issues/403

On Tuesday, December 29, 2015 at 4:48:37 PM UTC-5, Tim Allen wrote:
>
> Tim: that's definitely a big help, but still a click away. I'm just 
> brainstorming here, please bear with me!
>
> I think part of my confusion as a newbie is from the front page itself, at 
> https://docs.djangoproject.com/
>
> Now that I understand the concepts behind the documentation better (thanks 
> Daniele), it doesn't appear to be very well reflected on the front page. 
> There is a list of First steps, The model layer, and so on, but nothing in 
> the interface that clearly lets the user know that the documentation is 
> meant to be broken down into the "Tutorials / How-To / Explanation & 
> Discussion / Reference" paradigm. If that's what we are trying to 
> communicate, it should be shown to the user from the front of the 
> documentation clearly, IMHO.
>
> A top-down, browsable hierarchy would have been extremely useful to me 
> when I was just getting started. The ToC has the kind of hierarchy I'm 
> referring to (https://docs.djangoproject.com/en/1.9/contents/), but comes 
> across to the user as a wall of text / links. Perhaps developing the ToC 
> into a navigation menu is worth some effort?
>
> Does anyone else feel there is far too much on the front page? An 
> experienced Django dev will be more comfortable finding what they need 
> within the documentation, am I alone in thinking a much more simple front 
> page might be useful to the newcomer?
>
> Regards,
>
> Tim
>
> On Tuesday, December 29, 2015 at 11:25:40 AM UTC-5, Tim Graham wrote:
>>
>> I've refined Daniele's explanation here: 
>> https://github.com/django/django/pull/5888
>>
>> Let me know if it helps and what could be better.
>>
>> On Monday, December 28, 2015 at 11:31:30 PM UTC-5, Eric Holscher wrote:
>>>
>>>
>>>
>>> On Monday, December 28, 2015 at 4:52:36 PM UTC-8, Daniele Procida wrote:

 On Mon, Dec 28, 2015, Samuel Bishop  wrote:
 The main existing sections are: 

 * tutorials (/intro) 

 Tutorials take the new user by the hand through a series of steps. The 
 important thing isn't to explain all the steps, but to achieve something 
 useful with a minimum of effort. 

 After every step of a tutorial, the user should have something that 
 works, even if they barely understand what is happening (and it's not 
 necessary for them to understand, that can come later. What matters is 
 that 
 they are successful). 

 * how-to guides (/howto) 

 How-to guides are recipes that take the user through steps in key 
 subjects. They are more advanced than tutorials and assume a lot more 
 about 
 what the user already knows than tutorials do, and unlike documents in the 
 tutorial they can stand alone.   

 * discussion and explanation (/topic) 

 Aimed at explaining (at a fairly high level) rather than doing. 

 * reference (/ref) 

 Technical reference for APIs, key models and so on. It doesn't need to 
 explain so much as describe and instruct. 

  
>>> I think the above post does a good job of describing the layout, and 
>>> something similar should be included in the docs. Without having read 
>>> Jacob's posts on the subject, there is nothing in the official docs that 
>>> gives the reader an understanding that this is how things are laid out, as 
>>> far as I know.
>>>
>>> I think the underlying structure makes sense, and it seems that mostly 
>>> people are just upset about the lack of a pure auto-generated code 
>>> reference. I believe historically that this has been excluded explicitly, 
>>> not because of lack of technology. There is no use of autodoc in the Django 
>>> tree, even where it might make sense.
>>>
>>> At Django Under the Hood this year, I had a few conversations with folks 
>>> about rethinking and explicitly defining these policies. I think it makes a 
>>> lot of sense to write down the logic and structure behind these decisions 
>>> in a DEP, and explain the layout to doc users in a few places in the 
>>> documentation explicitly.
>>>
>>> Cheers,
>>> Eric 
>>>
>>

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

Re: structural & functional review of django documentation

[Eric Holscher]

On Tuesday, December 29, 2015 at 2:17:31 PM UTC-8, Tim Graham wrote:
>
>
> Turning the table of contents page into a CSS menu sounds like a possibly 
> worthwhile task.
>
> There is also an idea here for adding navigation breadcrumbs to the 
> documentation which might help:
> https://github.com/django/djangoproject.com/issues/403
>

Yea, I think the global TOC that the Read the Docs theme has is pretty good 
at surfacing the structure of the 
docs: http://docs.readthedocs.org/en/latest/ -- it allows users to see 
where in the hierarchy they are, and what levels make sense.

That is already what is generating the TOC that is on the contents page, so 
it would be pretty easy to include that in the sidebar for the docs (I 
believe it's the `toc` variable in the Jinja template, but Django is using 
the custom JSON backend, which works differently). I think Django's TOC is 
quite large, so it would be hard to make it fit nicely into the sidebar, 
but having the information available one each page would likely be useful 
for UX. Perhaps you could at least do the top-level items, and an expanded 
view of the current tree (the `collapse` option here 
http://sphinx-doc.org/templating.html#toctree)
 

>
>
> On Tuesday, December 29, 2015 at 4:48:37 PM UTC-5, Tim Allen wrote:
>>
>> Tim: that's definitely a big help, but still a click away. I'm just 
>> brainstorming here, please bear with me!
>>
>> I think part of my confusion as a newbie is from the front page itself, 
>> at https://docs.djangoproject.com/
>>
>> Now that I understand the concepts behind the documentation better 
>> (thanks Daniele), it doesn't appear to be very well reflected on the front 
>> page. There is a list of First steps, The model layer, and so on, but 
>> nothing in the interface that clearly lets the user know that the 
>> documentation is meant to be broken down into the "Tutorials / How-To / 
>> Explanation & Discussion / Reference" paradigm. If that's what we are 
>> trying to communicate, it should be shown to the user from the front of the 
>> documentation clearly, IMHO.
>>
>> A top-down, browsable hierarchy would have been extremely useful to me 
>> when I was just getting started. The ToC has the kind of hierarchy I'm 
>> referring to (https://docs.djangoproject.com/en/1.9/contents/), but 
>> comes across to the user as a wall of text / links. Perhaps developing the 
>> ToC into a navigation menu is worth some effort?
>>
>> Does anyone else feel there is far too much on the front page? An 
>> experienced Django dev will be more comfortable finding what they need 
>> within the documentation, am I alone in thinking a much more simple front 
>> page might be useful to the newcomer?
>>
>> Regards,
>>
>> Tim
>>
>> On Tuesday, December 29, 2015 at 11:25:40 AM UTC-5, Tim Graham wrote:
>>>
>>> I've refined Daniele's explanation here: 
>>> https://github.com/django/django/pull/5888
>>>
>>> Let me know if it helps and what could be better.
>>>
>>> On Monday, December 28, 2015 at 11:31:30 PM UTC-5, Eric Holscher wrote:



 On Monday, December 28, 2015 at 4:52:36 PM UTC-8, Daniele Procida wrote:
>
> On Mon, Dec 28, 2015, Samuel Bishop  wrote:
> The main existing sections are: 
>
> * tutorials (/intro) 
>
> Tutorials take the new user by the hand through a series of steps. The 
> important thing isn't to explain all the steps, but to achieve something 
> useful with a minimum of effort. 
>
> After every step of a tutorial, the user should have something that 
> works, even if they barely understand what is happening (and it's not 
> necessary for them to understand, that can come later. What matters is 
> that 
> they are successful). 
>
> * how-to guides (/howto) 
>
> How-to guides are recipes that take the user through steps in key 
> subjects. They are more advanced than tutorials and assume a lot more 
> about 
> what the user already knows than tutorials do, and unlike documents in 
> the 
> tutorial they can stand alone.   
>
> * discussion and explanation (/topic) 
>
> Aimed at explaining (at a fairly high level) rather than doing. 
>
> * reference (/ref) 
>
> Technical reference for APIs, key models and so on. It doesn't need to 
> explain so much as describe and instruct. 
>
>  
 I think the above post does a good job of describing the layout, and 
 something similar should be included in the docs. Without having read 
 Jacob's posts on the subject, there is nothing in the official docs that 
 gives the reader an understanding that this is how things are laid out, as 
 far as I know.

 I think the underlying structure makes sense, and it seems that mostly 
 people are just upset about the lack of a pure auto-generated code 
 reference. I believe historically that this has been excluded explicitly, 
 not because of lack of technology. There

Re: GenericForeignKey: loosening the requirements on the ContentType reference

[martin f krafft]

also sprach Shai Berger  [2015-12-10 08:38 +1300]:
> As far as I can see, you are trying to implement it in the model,
> rather than as a new kind of field. Try to write
> ExtendedGenericForeignKey, and I think things would look much
> better...

Hi, thanks for your response and sorry for taking such a long time
to follow-up.

I've tried implementing this as a field at the very beginning, but
I had an incredibly hard time figuring out which methods I need to
provide. I don't suppose you know of any guidelines, other than the
GenericForeignKey code (which I've still not fully understood) that
could help?

-- 
@martinkrafft | http://madduck.net/ | http://two.sentenc.es/
 
"you don't sew with a fork, so I see no reason
 to eat with knitting needles."
   -- miss piggy, on eating chinese food
 
spamtraps: madduck.bo...@madduck.net

-- 
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/20151230064017.GA21494%40fishbowl.rw.madduck.net.
For more options, visit https://groups.google.com/d/optout.


digital_signature_gpg.asc
Description: Digital signature (see http://martin-krafft.net/gpg/sig-policy/999bbcc4/current)