On Fri, Apr 24, 2009 at 5:36 AM, Pat LeSmithe <qed...@gmail.com> wrote:
>
> 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
--~--~---------~--~----~------------~-------~--~----~
To post to this group, send email to sage-devel@googlegroups.com
To unsubscribe from this group, send email to
sage-devel-unsubscr...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sage-devel
URLs: http://www.sagemath.org
-~----------~----~----~----~------~----~------~--~---
