Dedicated CSS classes for docfields (e.g. `:param:`, `:returns:`)
#773 opened on Jan 2, 2015
Description
See http://groups.google.com/group/sphinx-dev/msg/52cf4b91e802f286
Subject: :param: and :keyword: rendering
On 16 Oct 2010, 20:41:23 from Vinay Sajip
Is there an easy way to have these styled differently, so it's more
obvious what the keyword parameters are? Especially when the method
signature uses **kwargs.
Is there a particular reason why the distinction is there? Is the fact that param, parameter, arg, argument, key, keyword are all offered just to accommodate the preferences of different users?
If would be neater if instead of <strong>param_name</strong>, the
output markup was something like
<span class="positional-param">param_name</span>
and
<span class="keyword-param">param_name</span>
Regards,
Vinay Sajip
On 8 Jan 2011, 23:03:00 from Georg Brandl
Is there an easy way to have these styled differently, so it's more obvious what the keyword parameters are? Especially when the method signature uses
**kwargs.Is there a particular reason why the distinction is there? Is the fact that param, parameter, arg, argument, key, keyword are all offered just to accommodate the preferences of different users?
Yes, and different names used by different documentation tools.
If would be neater if instead of
<strong>param_name</strong>, the output markup was something like
<span class="positional-param">param_name</span>and
<span class="keyword-param">param_name</span>
They would still all be in one list, so how would you style them differently (without confusing the user)?
Georg
On 9 Jan 2011, 21:46:38 from Vinay Sajip
Hi Georg,
If would be neater if instead of
<strong>param_name</strong>, the
output markup was something like
<span class="positional-param">param_name</span>and
<span class="keyword-param">param_name</span>They would still all be in one list, so how would you style them differently (without confusing the user)?
Perhaps using italic for one but not the other. It would be a convention that would have to be explained in the "typographic conventions" part of the documentation, but that's not a problem. Having the markup I suggested would at least allow alternative styling to be done, even if the two types of parameters have the same default styling and many people leave it as is.
Regards,
Vinay
On 11 Jan 2011, 11:29:43 from Günter Milde
I suggest <emph> or <strong> tags with class="parameter positional" vs.
class="parameter keyword" so that even without a stylesheet the emphasis
is kept (graceful degradation) but configuring the layout with CSS is
easy.
Using two class arguments ("parameter keyword") instead of a hyphenated
one ("parameter-keyword") allows setting shared features in a common rule
and diffentiating with the selectors .parameter.keyword vs.
.parameter.positional.
Günter
On 12 Jan 2011, 08:14:55 from Günter Milde
I suggest
<emph>or<strong>tags withclass="parameter positional"vs.class="parameter keyword"so that even without a stylesheet the emphasis is kept (graceful degradation) but configuring the layout with CSS is easy.
Using two class arguments ("parameter keyword") instead of a hyphenated one ("parameter-keyword") allows setting shared features in a common rule and diffentiating with the selectors
.parameter.keywordvs..parameter.positional.
Addition: to avoid confusion with keywords of a programming language, I
change my suggestion to <strong class="parameter kwarg">
(i.e. "kwarg" instead of "keyword").
Günter
On 12 Jan 2011, 08:28:32 from Georg Brandl
That sounds like a good compromise. I'll see what I can do :)
Georg
On 12 Jan 2011, 11:36:24 from Fred L. Drake, Jr
Addition: to avoid confusion with keywords of a programming language, I change my suggestion to
<strong class="parameter kwarg">(i.e. "kwarg" instead of "keyword").
If we look back at how the old \keyword{...} was used in the LaTeX
system, it was specifically to mark language keywords, not keyword
parameters.
Whether this was valuable over \code{...} is open to debate.
(\kwindex{...}, generating an index entry, was separate.)
-Fred
On 12 Jan 2011, 19:18:43 from Georg Brandl
Addition: to avoid confusion with keywords of a programming language, I change my suggestion to
<strong class="parameter kwarg">(i.e. "kwarg" instead of "keyword").If we look back at how the old
\keyword{...}was used in the LaTeX system, it was specifically to mark language keywords, not keyword parameters.Whether this was valuable over
\code{...}is open to debate. (\kwindex{...}, generating an index entry, was separate.)
It probably wasn't valuable; the equivalent :keyword:`foo` in Sphinx is
valuable since it generates a link to the keyword's definition in the
language reference.
cheers, Georg
On 12 Jan 2011, 20:57:20 from Fred L. Drake, Jr
It probably wasn't valuable; the equivalent
:keyword:`foo`in Sphinx is valuable since it generates a link to the keyword's definition in the language reference.
Nice! But you knew that already. ;-)
- Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/773
- Originally reported by: Georg Brandl
- Originally created at: 2011-09-23T11:30:38.683