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 2009/4/24 Carl Witty <carl.wi...@gmail.com>: > > 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 -~----------~----~----~----~------~----~------~--~---
