Hi all, Django currently uses a custom transform class when building docs using Sphinx. What this does is attempt to find blockquote elements and pull their contents up a level, discarding the now empty blockquote element.
The reason for this appears to be that it allows you to write restructured text with extra levels of indentation which would normally be interpreted as a blockquote. I don't think this is a good idea. First, it means that we are writing our docs in a non-standard dialect of ReST - not just adding things, but changing things. To me this seems to be just an unnecessary nuisance and complication. Is there a good reason for it? It seems to have been in the code base since a docs re-organisation in 2008. Second, it doesn't work very well - see this page: http://goo.gl/aoZKv Compare the 'select' sub-section and the 'order' sub-section, which still has a blockquote in it. There are about 32 instances of blockquote in our built docs which I'm guessing shouldn't be there. (They are styled simply as indentation on docs.djangoproject.com, but not in other places). Would we consider removing this custom transform? If we did, in addition to the 32 instance of indentation that already need fixing, there are 12 other instances that would need fixing. (These places can be found easily by grepping the output for '<blockquote', with/without the transform applied). These relative figures on their own suggest the confusion added is greater than the benefit received - we are only making correct use of this feature in 12 places, and messing up in 32 places. Regards, Luke -- "Mediocrity: It takes a lot less time, and most people don't realise until it's too late." (despair.com) Luke Plant || http://lukeplant.me.uk/ -- You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to django-developers@googlegroups.com. To unsubscribe from this group, send email to django-developers+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.
