[sage-devel] Re: documentation issues
Not all of Chris's original questions have been answered yet in this 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 mabsh...@googlemail.com: On Apr 23, 9:34 pm, Jason Grout jason-s...@creativetrax.com wrote: Carl Witty wrote: On Thu, Apr 23, 2009 at 9:19 PM, Jason Grout jason-s...@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.) 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. Mike mentioned the update to 0.6 should be easy, but he hadn't done it yet. But I think this should be doable in the 4.0 timeframe. Jason Cheers, Michael --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sage-devel] Re: documentation issues
On Thu, Apr 23, 2009 at 10:03 PM, Jason Grout jason-s...@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. 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 #f4. 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 --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sage-devel] Re: documentation issues
2009/4/24 David Joyner wdjoy...@gmail.com: On Thu, Apr 23, 2009 at 10:03 PM, Jason Grout jason-s...@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 BW throughout? John 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 #f4. 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 --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sage-devel] Re: documentation issues
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. 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: http://trac.sagemath.org/sage_trac/ticket/5653 --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sage-devel] Re: documentation issues
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(): rexclude 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 -~--~~~~--~~--~--~---
[sage-devel] Re: documentation issues
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(): rexclude 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 -~--~~~~--~~--~--~---
[sage-devel] Re: documentation issues
On Apr 24, 9:25 am, John Cremona john.crem...@gmail.com wrote: 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 In case underscored methods are not added to the reference manual any 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 --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sage-devel] Re: documentation issues
On Fri, Apr 24, 2009 at 8:09 AM, Carl Witty carl.wi...@gmail.com wrote: 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 --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sage-devel] Re: documentation issues
chris wuthrich wrote: 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 #f4. 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 --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sage-devel] Re: documentation issues
On Thu, Apr 23, 2009 at 7:03 PM, Jason Grout jason-s...@creativetrax.com wrote: chris wuthrich wrote: 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 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 #f4. 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 --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sage-devel] Re: documentation issues
William Stein wrote: 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 #f4. 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 --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sage-devel] Re: documentation issues
On Thu, Apr 23, 2009 at 9:19 PM, Jason Grout jason-s...@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 --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sage-devel] Re: documentation issues
Carl Witty wrote: On Thu, Apr 23, 2009 at 9:19 PM, Jason Grout jason-s...@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.) 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 --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sage-devel] Re: documentation issues
On Apr 23, 9:34 pm, Jason Grout jason-s...@creativetrax.com wrote: Carl Witty wrote: On Thu, Apr 23, 2009 at 9:19 PM, Jason Grout jason-s...@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.) 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. Mike mentioned the update to 0.6 should be easy, but he hadn't done it yet. But I think this should be doable in the 4.0 timeframe. Jason Cheers, Michael --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
