documentation issues
chris wuthrich
i have some questions and suggestion on the RestructuredText. I am a
ReST-newbie and so maybe these things have been discussed before.
* In one of my files i have a line "power_series = series". This
produces the full docstring of series to appear twice in the
documentation, once under series and once under power_series. How can
I exclude the alias ?
* Generally I am very happy with the outputs of the documentation
using sphinx. But there are some improvement that one could think
about. For instance I think there are too many different fonts used,
that is a bit ugly. More importantly I think that the examples and the
warnings are more emphasized than the actual command that is
documented. Also the commands and not well-seperated. To someone who
is not used, this might look confusing. Of course, I have absolutely
no idea if this can be changed or not.
* The docstrings become much longer now that we have to add
additional empty lines. This is not very nice when using foo? or tab-
completion in the notebook. Also the `` `` are annoying there. Is it
not possible that the printing of the docstring there is simplified ?
* Where do we put references to books and articles ? Within the
function or the header of the file ? With [XY]_ ?
* Accents again. I know that we should not put them in the py-files.
Could we have a predefined |eacute| maybe ?
Chris.
Jason Grout
>
> i have some questions and suggestion on the RestructuredText. I am a
> ReST-newbie and so maybe these things have been discussed before.
>
> * In one of my files i have a line "power_series = series". This
> produces the full docstring of series to appear twice in the
> documentation, once under series and once under power_series. How can
> I exclude the alias ?
>
> * Generally I am very happy with the outputs of the documentation
> using sphinx. But there are some improvement that one could think
> about. For instance I think there are too many different fonts used,
> that is a bit ugly. More importantly I think that the examples and the
> warnings are more emphasized than the actual command that is
> documented. Also the commands and not well-seperated. To someone who
> is not used, this might look confusing. Of course, I have absolutely
> no idea if this can be changed or not.
>
> * The docstrings become much longer now that we have to add
> additional empty lines. This is not very nice when using foo? or tab-
> completion in the notebook. Also the `` `` are annoying there. Is it
> not possible that the printing of the docstring there is simplified ?
Soon we will have html documentation in the notebook, so this won't be
an issue there.
On a different note, can we change the background color of examples? In
my opinion, that green is just a bit too strong. It's also hard to read
the blue text in strings against the green background. (After playing
with it for a while) I propose a soft light yellowish off-white color,
like #fffff4. The syntax highlight colors stand out better, and the
whole thing is easier to read. Plus, the barely-yellow color matches
nicely with the blue-green of the titlebar, etc.
Thanks,
Jason
William Stein
It's not green, it is grey, and I also really don't like it either.
> It's also hard to read
> the blue text in strings against the green background. (After playing
> with it for a while) I propose a soft light yellowish off-white color,
> like #fffff4. The syntax highlight colors stand out better, and the
> whole thing is easier to read. Plus, the barely-yellow color matches
> nicely with the blue-green of the titlebar, etc.
A big <font size=+5>+1</font> to that!
William
Jason Grout
>>
>> On a different note, can we change the background color of examples? In
>> my opinion, that green is just a bit too strong.
>
> It's not green, it is grey, and I also really don't like it either.
It's definitely a light green for me in firefox on ubuntu (it's color
#EEFFCC, which you can see from the hex has a strong green component).
The heading backgrounds are grey. But no matter, at least we agree it
ought to be changed.
>
>> It's also hard to read
>> the blue text in strings against the green background. (After playing
>> with it for a while) I propose a soft light yellowish off-white color,
>> like #fffff4. The syntax highlight colors stand out better, and the
>> whole thing is easier to read. Plus, the barely-yellow color matches
>> nicely with the blue-green of the titlebar, etc.
>
> A big <font size=+5>+1</font> to that!
Anyone know where the CSS file is? The color is set in a default.css
file, but the only default.css files I see are in _static directories,
which sounds like they are automatically generated somehow.
Thanks,
Jason
Carl Witty
<jason...@creativetrax.com> wrote:
> Anyone know where the CSS file is? The color is set in a default.css
> file, but the only default.css files I see are in _static directories,
> which sounds like they are automatically generated somehow.
It comes (originally) from src/sphinx/static/default.css in the sphinx
spkg. (No, I don't know the right way to customize it.)
Carl
Jason Grout
It looks like 0.6 is easy to theme: http://sphinx.pocoo.org/theming.html
We are running 0.5.1. The current release is 0.6.1. Is anyone working
on an upgrade? Should it be a drop-in replacement? Mike, you mentioned
the autodoc in 0.6 will make some other things easier too.
Jason
mabshoff
yet. But I think this should be doable in the 4.0 timeframe.
> Jason
Cheers,
Michael
John Cremona
thread -- for example, listing of aliases, and making the function
(and even more, the class) headings more prominent. I will not
mention accents.
John
2009/4/24 mabshoff <mabs...@googlemail.com>:
David Joyner
<jason...@creativetrax.com> wrote:
>
> chris wuthrich wrote:
>>
...
>
> On a different note, can we change the background color of examples? In
see what they look like on a printed (B+W) page? If the
color->B+W rendering is too faint then the printed version of the tutorial
will be unreadable.
John Cremona
> On Thu, Apr 23, 2009 at 10:03 PM, Jason Grout
> <jason...@creativetrax.com> wrote:
>>
>> chris wuthrich wrote:
>>>
>
> ...
>
>
>>
>> On a different note, can we change the background color of examples? In
>
>
> Before making color changes, can they please be tested to
> see what they look like on a printed (B+W) page? If the
> color->B+W rendering is too faint then the printed version of the tutorial
> will be unreadable.
those B&W throughout?
John
David Joyner
>
> 2009/4/24 David Joyner <wdjo...@gmail.com>:
>>
>> On Thu, Apr 23, 2009 at 10:03 PM, Jason Grout
>> <jason...@creativetrax.com> wrote:
>>>
>>> chris wuthrich wrote:
>>>>
>>
>> ...
>>
>>
>>>
>>> On a different note, can we change the background color of examples? In
>>
>>
>> Before making color changes, can they please be tested to
>> see what they look like on a printed (B+W) page? If the
>> color->B+W rendering is too faint then the printed version of the tutorial
>> will be unreadable.
>
> Presumably you mean to only print the pdf versions
> -- why not make those B&W throughout?
There are a long list of color definitions in the preamble.
I guess if I wasn't so lazy I could just edit them all line-by-line?
Pat LeSmithe
> * In one of my files i have a line "power_series = series". This
> produces the full docstring of series to appear twice in the
> documentation, once under series and once under power_series. How can
> I exclude the alias ?
According to
http://sphinx.pocoo.org/ext/autodoc.html
the autodoc directives
.. autoclass:: pAdicLseriesOrdinary
:members: series, is_ordinary, is_supersingular
might work in Sphinx v0.5 and
.. autoclass:: pAdicLseriesOrdinary
:exclude-members: power_series
in Sphinx v0.6. However, I believe the current version of builder.py
does not scan for custom directives when it auto-generates the .rst
files. I don't know if it's OK simply to put them in a docstring.
Another possibility is to add to builder.py an auto-skip-member()
handler that skips certain methods, along the lines of
except that it scans the first part of a __doc__ attribute for some phrase.
I can't spend any more time on this, however.
> * The docstrings become much longer now that we have to add
> additional empty lines. This is not very nice when using foo? or tab-
> completion in the notebook. Also the `` `` are annoying there. Is it
> not possible that the printing of the docstring there is simplified ?
I think these are subsumed by this ticket:
Carl Witty
>
> chris wuthrich wrote:
>> * In one of my files i have a line "power_series = series". This
>> produces the full docstring of series to appear twice in the
>> documentation, once under series and once under power_series. How can
>> I exclude the alias ?
>
> According to
>
> http://sphinx.pocoo.org/ext/autodoc.html
>
> the autodoc directives
>
> .. autoclass:: pAdicLseriesOrdinary
> :members: series, is_ordinary, is_supersingular
>
> might work in Sphinx v0.5 and
>
> .. autoclass:: pAdicLseriesOrdinary
> :exclude-members: power_series
>
> in Sphinx v0.6. However, I believe the current version of builder.py
> does not scan for custom directives when it auto-generates the .rst
> files. I don't know if it's OK simply to put them in a docstring.
>
> Another possibility is to add to builder.py an auto-skip-member()
> handler that skips certain methods, along the lines of
>
> http://groups.google.com/group/sphinx-dev/browse_thread/thread/852fbec28bc4ba15/719dbcf762c9db18?#719dbcf762c9db18
>
>
> except that it scans the first part of a __doc__ attribute for some phrase.
Of course, looking at __doc__ for a keyword won't help distinguish
power_series from series after "power_series = series".
I definitely do like the idea of using keywords to the docstrings to
control whether they show up in the reference manual, though. (This
could override the current decision, which I think is "non-underscore
methods are included, underscore methods are not".)
It seems like the first line of the docstring (on the same line as the
triple-quotes) would be a good place for such a keyword:
def foo():
r"""exclude
Docs for foo.
"""
pass
I really want about three different levels of reference manual for a
lot of my code. For instance, sage/misc/sage_input.py has one
function that's useful to people working from the command line or
notebook, one class (with a bunch of methods) that's useful to people
writing Sage library code (writing new types, and wanting to support
sage_input on those types), and a bunch of classes that are only
useful to people (only me, so far) working on sage_input itself. It
would be nice to be able to mark these ("public", "library", and
"private", perhaps), and then be able to produce three different
reference manuals (small, medium, and huge) with different subsets of
the documentation.
As far as aliases go, it should be possible to automatically detect
aliases inside sphinx and produce appropriate documentation (once we
decide what the appropriate documentation is). (This would mean
patching sphinx, or forking the autodoc extension; hopefully this
would be considered a useful feature that would be accepted upstream.)
Carl
John Cremona
which should be in the ref manual. If nothing else, then the __init__
functions of classes. When restifying files I have made sure that all
the EXAMPLES:: from __init__ functions are copied into the class's own
docstring since then they do appear in the ref manual.
John
2009/4/24 Carl Witty <carl....@gmail.com>:
Pat LeSmithe
> Of course, looking at __doc__ for a keyword won't help distinguish
> power_series from series after "power_series = series".
Oops. I just found this:
By the way, I did try something [silly] like
def skippy(app, what, name, obj, skip, options):
if name ==
'sage.schemes.elliptic_curves.padic_lseries.pAdicLseriesOrdinary.power_series':
return True
return skip
def setup(app):
app.connect('autodoc-process-docstring', process_docstring_cython)
app.connect('autodoc-process-docstring', process_docstring_module_title)
app.connect('autodoc-skip-member', skippy)
in builder.py, but the name argument is not fully-qualified in v0.5.1.
Looking at around line 540 of autodoc.py, I think
skip_user = self.env.app.emit_firstresult(
'autodoc-skip-member', what, membername, member, skip, self.options)
should instead use
full_membername = fullname + '.' + membername
which is defined a bit later.
The v0.6x documentation, at least, mentions a FQON (O = object).
John H Palmieri
> I agree with all of this -- there are plenty of underscored functions
> which should be in the ref manual. If nothing else, then the __init__
> functions of classes. When restifying files I have made sure that all
> the EXAMPLES:: from __init__ functions are copied into the class's own
> docstring since then they do appear in the ref manual.
>
> John
time soon, I've been working on a patch for the developer's guide
suggesting exactly what you do: put the bulk of the documentation in
the class's docstring, not in the __init__ docstring. See
<http://trac.sagemath.org/sage_trac/ticket/5588>.
John
Mike Hansen
> As far as aliases go, it should be possible to automatically detect
> aliases inside sphinx and produce appropriate documentation (once we
> decide what the appropriate documentation is). (This would mean
> patching sphinx, or forking the autodoc extension; hopefully this
> would be considered a useful feature that would be accepted upstream.)
Yes, this is relatively easy to do since the __name__ of an aliased
method is different than the name in the class namespace under which
it appears. For example,
sage: x.numerical_approx.__name__
'n'
--Mike