Agreed with Alex. I brought this up on IRC a month or so ago, and the
(small) consensus was that it'd be great to have the ":real markup:"
generate TOC entries the way we want it to, but that doing so involves
hacking Sphinx (or at best writing a plugin for it) and nobody was
ready to jump into that project at the time. The issue had been raised
before on the Sphinx mailing list, but didn't get a lot of response.
However, to answer your question for the time being:
In the reference documentation I don't mind the use of the backticks
in the headings for methods/attributes. Since the backticks cause the
entry in the TOC to show up in white instead of yellow it offers a
visual distinction which I think is helpful. I'd carry that
distinction through to any future Sphinx improvements that would allow
us to get rid of those headings altogether.
All the best,
- Gabriel
On Nov 25, 12:27 pm, Alex Gaynor <alex.gay...@gmail.com> wrote:
> On Thu, Nov 25, 2010 at 2:25 PM, Adam V. <fla...@gmail.com> wrote:
> > The docs seem a bit inconsistent on the use of raw lines for headings
> > that describe classes/methods/attributes.
>
> > The stated preference is to use a directive before the heading to make
> > it easier to link. Is there also a preference on whether these
> > headings should be raw quoted or normal text?
>
> > FWIW, my personal preference would be to remove quoting from API docs,
> > so for instance, remove it from the headings on this page
> >http://docs.djangoproject.com/en/dev/ref/forms/fields/for the field
> > and class names.
>
> > But mostly I just want to know what the official stance is, if any.
>
> > Thanks.
>
> > --
> > You received this message because you are subscribed to the Google Groups
> > "Django developers" group.
> > To post to this group, send email to django-develop...@googlegroups.com.
> > To unsubscribe from this group, send email to
> > django-developers+unsubscr...@googlegroups.com.
> > For more options, visit this group
> > athttp://groups.google.com/group/django-developers?hl=en.
>
> Personally I'd prefer that we only have the :real-markup:, however as
> it doesn't generate actual TOC entries it makes them near useless. If
> someone, <wink />, were to figure out how to have those it would be
> awesome ;)
>
> Alex
>
> --
> "I disapprove of what you say, but I will defend to the death your
> right to say it." -- Voltaire
> "The people's good is the highest law." -- Cicero
> "Code can always be simpler than you think, but never as simple as you
> want" -- Me
--
You received this message because you are subscribed to the Google Groups
"Django developers" group.
To post to this group, send email to django-develop...@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.
