Custom transform in django docs
Luke Plant
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:
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/
Chris Beaven
Luke Plant
> 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.
I was wrong about this - there are actually about 60 places where we are
making use this feature in the docs, in less than 10 files. I still
think we should fix them.
Any objections?
Luke
--
"My capacity for happiness you could fit into a matchbox without
taking out the matches first." (Marvin the paranoid android)
Luke Plant || http://lukeplant.me.uk/
Carl Meyer
Hash: SHA1
On 10/10/2011 09:40 AM, Luke Plant wrote:
> I was wrong about this - there are actually about 60 places where we are
> making use this feature in the docs, in less than 10 files. I still
> think we should fix them.
>
> Any objections?
+1 from me - I think the bar should be pretty high for what's worth a
departure from standard ReST syntax, and this doesn't seem to meet that
bar as far as I can tell.
Carl
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
iEYEARECAAYFAk6TFi4ACgkQ8W4rlRKtE2cb2QCggHtMm2Fz9dvvolEb4VmYLV9q
pe8AnjLamoVNAHqJ5PxcS8FIcTPAIC/0
=S+Kk
-----END PGP SIGNATURE-----
Jacob Kaplan-Moss
> 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.
Heh, so actually funny story.
Turns out I copied this hack was over from the code I used for the
Django book. We did it there to surpress a difference between the HTML
conversion we used on the website and the OpenOffice conversion we
used for the print publication. So it's actually an artifact of our
hacked together book toolchain. I'm pretty surprised that it's still
there -- I'd totally forgotten about this hack.
By all means rip it out.
Jacob
Gabriel Hurley
Luke Plant
> Heh, so actually funny story.
>
> Turns out I copied this hack was over from the code I used for the
> Django book. We did it there to surpress a difference between the HTML
> conversion we used on the website and the OpenOffice conversion we
> used for the print publication. So it's actually an artifact of our
> hacked together book toolchain. I'm pretty surprised that it's still
> there -- I'd totally forgotten about this hack.
Ah, well that explains it! It's gone now :-)
Luke
--
"Oh, look. I appear to be lying at the bottom of a very deep, dark
hole. That seems a familiar concept. What does it remind me of? Ah,
I remember. Life." (Marvin the paranoid android)
Luke Plant || http://lukeplant.me.uk/
Ramiro Morales
>
> Ah, well that explains it! It's gone now :-)
Belated +1 to this -- Great finding and fix Luke.
But it seems this is affecting styling of locally generated builds of
the HTML version of the docs.
Fon an example see (from tutorial part #1) http://i.imgur.com/CQrjo.png
Compare that with:
https://docs.djangoproject.com/en/dev/intro/tutorial01/
There are a lot of other bulleted (and numbered?) lists in our docs that sport
the same green vertical bar at the left as the two-elements one at the top
of that page.
Looking at the ReST documentation[1] it seems the indentation we use for
such lists are non-conventional and would explain this.
Can anybody confirm this?. If so, we have a bunch of documentation
.txt files to tweak.
(also, if/when we fix this we should verify that we don't break the stylin
of the affected parts in the docs.djangoproject.com)
Regards,
--
Ramiro Morales
1. http://docutils.sourceforge.net/docs/user/rst/quickstart.html#lists
Carl Meyer
Hash: SHA1
Hi Ramiro,
On 10/13/2011 05:35 AM, Ramiro Morales wrote:
> Belated +1 to this -- Great finding and fix Luke.
Indeed.
> But it seems this is affecting styling of locally generated builds of
> the HTML version of the docs.
>
> Fon an example see (from tutorial part #1) http://i.imgur.com/CQrjo.png
>
> Compare that with:
>
> https://docs.djangoproject.com/en/dev/intro/tutorial01/
>
> There are a lot of other bulleted (and numbered?) lists in our docs that sport
> the same green vertical bar at the left as the two-elements one at the top
> of that page.
>
> Looking at the ReST documentation[1] it seems the indentation we use for
> such lists are non-conventional and would explain this.
>
> Can anybody confirm this?. If so, we have a bunch of documentation
> .txt files to tweak.
>
> (also, if/when we fix this we should verify that we don't break the stylin
> of the affected parts in the docs.djangoproject.com)
I ran into the same problem on the "These files are:" list further down
that same page when working on #15372. I checked the standard ReST
syntax, de-indented the list as part of my patch, and it fixed the
problem locally. It also doesn't seem to have caused any problem on
docs.djangoproject.com.
If you view source on docs.djangoproject.com, that two-element list up
top is in fact wrapped in a blockquote, it's just that apparently the
dp.com styles don't style blockquotes. The blockquote doesn't make any
sense semantically, so I vote we do fix the list indentation throughout
the docs to get rid of the spurious blockquotes.
Carl
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
iEYEARECAAYFAk6XFDcACgkQ8W4rlRKtE2cOBgCggSK/h7vYlqw5uQnh9zxT4ZVX
9i8AnAxsx7/UxrS65COC8llUuTN0ypdZ
=dgJo
-----END PGP SIGNATURE-----
Luke Plant
> Belated +1 to this -- Great finding and fix Luke.
>
> But it seems this is affecting styling of locally generated builds of
> the HTML version of the docs.
>
> Fon an example see (from tutorial part #1) http://i.imgur.com/CQrjo.png
>
> Compare that with:
>
> https://docs.djangoproject.com/en/dev/intro/tutorial01/
>
> There are a lot of other bulleted (and numbered?) lists in our docs that sport
> the same green vertical bar at the left as the two-elements one at the top
> of that page.
>
> Looking at the ReST documentation[1] it seems the indentation we use for
> such lists are non-conventional and would explain this.
>
> Can anybody confirm this?. If so, we have a bunch of documentation
> .txt files to tweak.
As Carl pointed out, these are caused by the blockquote element inserted
whenever the list is indented by 1 or more characters (as per ReST
specification). It also applied to other things.
I thought I had fixed all the instances of this when I committed my
patch. However, I'm not sure exactly how, but I think I must have been
caught out by cached Sphinx build files, as I only got a minority of
them when I grepped for them - there were several hundreds more! I might
not have attempted this if I had correctly counted at the beginning...
but anyway, I've fixed them all now (hopefully!).
It seems we were relying on this hack in *lots* of places, not just in
the docs that originated from Jacob's import of docs.
> (also, if/when we fix this we should verify that we don't break the stylin
> of the affected parts in the docs.djangoproject.com)
There is currently a problem with docs.djangoproject.com in that it
doesn't display blockquotes visibly at all. There are 4 places in our
docs that have genuine blockquotes, but you can't see where the
quotation finishes due to lack of styling. I've sent Jacob a pull
request for this already, to bring it inline with offline docs. (This is
also the reason why we didn't see the hundreds of instances of
blockquote in the docs on docs.djangoproject.com).
Luke
--
O'REILLY'S LAW OF THE KITCHEN
Cleanliness is next to impossible.
Luke Plant || http://lukeplant.me.uk/
Ramiro Morales
On Thu, Oct 13, 2011 at 9:16 PM, Luke Plant <L.Pla...@cantab.net> wrote:
>
> [...]
> there were several hundreds more! I might
> not have attempted this if I had correctly counted at the beginning...
> but anyway, I've fixed them all now (hopefully!).
>
> It seems we were relying on this hack in *lots* of places, not just in
> the docs that originated from Jacob's import of docs.
Wow that was fast. Thanks!
--
Ramiro Morales