My 2 cents: I think it looks better if you reduce the number of histogram bins from 50 down to 15 or 20. Gary R. John Hunter wrote: > I played around with this a bit this morning -- it may be too busy for > your OS X sensibilities, but let me know if you think think this is an > approach wotrh pursuing. I've added the mathtext background and a few > axes and there are a few more axes to do. In svn as > examples/api/logo2.py
On Friday 23 May 2008 04:34:11 pm John Hunter wrote: > On Fri, May 23, 2008 at 3:31 PM, Darren Dale <dar...@co...> wrote: > > commit yout customizing.txt? > > done. > > I just discovered l > > > # The name of an image file (within the static path) to place at the > top of # the sidebar. > #html_logo = 'logo.png' > > so I have to get to work creating a new cool mpl figure for the logo. > Our old banner is so 70s. I wasn't going to say it... but yeah. :) I think we need to set a policy on how we are going to handle code in docstrings. There are lots of places where indentation and asterisks are causing trouble. Should examples be codeblocks (::) or doctests (>>>)? I think inlines should just be `` quoted, like: data are plotted as ``plot(lags, c, **kwargs)`` Here is an example from axes.Axes: def xcorr(self, x, y, normed=False, detrend=mlab.detrend_none, usevlines=False, maxlags=None, **kwargs): """ XCORR(x, y, normed=False, detrend=mlab.detrend_none, usevlines=False, **kwargs):a Can we eliminate the call signature? I think this is only necessary for extension code, the call signature will already be displayed by sphinx and by pythons interactive help. Regarding the crazy pyplot error, I'm doing it the slow, painful way, including a few members at a time in the members list and fixing the errors that arise. Darren
On Fri, May 23, 2008 at 3:47 PM, Darren Dale <dar...@co...> wrote: >> so I have to get to work creating a new cool mpl figure for the logo. >> Our old banner is so 70s. > > I wasn't going to say it... but yeah. :) Thanks for your sensitivity :-) I made that a long time ago when I was really proud that I could set the font size on text! > I think we need to set a policy on how we are going to handle code in > docstrings. There are lots of places where indentation and asterisks are > causing trouble. Should examples be codeblocks (::) or doctests (>>>)? I > think inlines should just be `` quoted, like: > > data are plotted as ``plot(lags, c, **kwargs)`` Works for me -- we should prefer code blocks whether than inlines just because they are more readable w/o the quotes, but if we need inlines in some cases we'll use 'em > Here is an example from axes.Axes: > > def xcorr(self, x, y, normed=False, detrend=mlab.detrend_none, > usevlines=False, maxlags=None, **kwargs): > """ > XCORR(x, y, normed=False, detrend=mlab.detrend_none, usevlines=False, > **kwargs):a > > Can we eliminate the call signature? I think this is only necessary for > extension code, the call signature will already be displayed by sphinx and by > pythons interactive help. Unfortunately, I think we need it. pyplot xcorr is just a *args, **kwargs pass though to Axes.xcorr, so if you do help pyplot.xcorr you won't see the signature, which is why we manually copy the signature in axes.py. In [89]: help pyplot.xcorr Help on function xcorr in module matplotlib.pyplot: xcorr(*args, **kwargs) XCORR(x, y, normed=False, detrend=mlab.detrend_none, usevlines=False, **kwargs): Plot the cross correlation between x and y. If normed=True, normalize the data but the cross correlation at 0-th lag. x and y are detrended by the detrend callable (default no normalization. x and y must be equal length We could use a codeblock in axes.py def xcorr(self, x, y, normed=False, detrend=mlab.detrend_none, usevlines=False, maxlags=None, **kwargs): """ pyplot signature: xcorr(x, y, normed=False, detrend=mlab.detrend_none, usevlines=False, **kwargs): Plot the cross correlation between x and y. If normed=True, normalize the data but the cross correlation at 0-th lag. x and y are detrended by the detrend callable (default no > Regarding the crazy pyplot error, I'm doing it the slow, painful way, > including a few members at a time in the members list and fixing the errors > that arise. Ugg, I don't envy you. Perhaps a message to the maintainer about the need for some verbose context in these error messages would be more expeditious. We have a lot of these to do. Another feature I'd like to see is a macro location parameter. Eg define location:`mplexamples` = ../../examples/pyplot and then later be able to refer to that .. literalinclude:: location:`mplexamples`/simple_plot.py with whatever syntax is appropriate so as we reorganize we don't have to keep fixing the relative path structure. Eg, I am including icons from mpl/data/images in the navigation toolbar section.... JDH
On Friday 23 May 2008 04:57:24 pm John Hunter wrote: > On Fri, May 23, 2008 at 3:47 PM, Darren Dale <dar...@co...> wrote: > >> so I have to get to work creating a new cool mpl figure for the logo. > >> Our old banner is so 70s. > > > > I wasn't going to say it... but yeah. :) > > Thanks for your sensitivity :-) haha! I hope you stick with your eeg, its just the colorscheme and fonts that are outdated. > I made that a long time ago when I was > really proud that I could set the font size on text! > > > I think we need to set a policy on how we are going to handle code in > > docstrings. There are lots of places where indentation and asterisks are > > causing trouble. Should examples be codeblocks (::) or doctests (>>>)? I > > think inlines should just be `` quoted, like: > > > > data are plotted as ``plot(lags, c, **kwargs)`` > > Works for me -- we should prefer code blocks whether than inlines just > because they are more readable w/o the quotes, but if we need inlines > in some cases we'll use 'em > > > Here is an example from axes.Axes: > > > > def xcorr(self, x, y, normed=False, detrend=mlab.detrend_none, > > usevlines=False, maxlags=None, **kwargs): > > """ > > XCORR(x, y, normed=False, detrend=mlab.detrend_none, usevlines=False, > > **kwargs):a > > > > Can we eliminate the call signature? I think this is only necessary for > > extension code, the call signature will already be displayed by sphinx > > and by pythons interactive help. > > Unfortunately, I think we need it. pyplot xcorr is just a *args, > **kwargs pass though to Axes.xcorr, so if you do help pyplot.xcorr you > won't see the signature, which is why we manually copy the signature > in axes.py. Oh, right. > In [89]: help pyplot.xcorr > Help on function xcorr in module matplotlib.pyplot: > > xcorr(*args, **kwargs) > XCORR(x, y, normed=False, detrend=mlab.detrend_none, > usevlines=False, **kwargs): > > Plot the cross correlation between x and y. If normed=True, > normalize the data but the cross correlation at 0-th lag. x > and y are detrended by the detrend callable (default no > normalization. x and y must be equal length > > We could use a codeblock in axes.py > def xcorr(self, x, y, normed=False, detrend=mlab.detrend_none, > usevlines=False, > maxlags=None, **kwargs): > """ > pyplot signature: > > xcorr(x, y, normed=False, detrend=mlab.detrend_none, > usevlines=False, **kwargs): > > Plot the cross correlation between x and y. If normed=True, > normalize the data but the cross correlation at 0-th lag. x > and y are detrended by the detrend callable (default no How about Use:, or Usage: or Signature:? Most of these exist outside of pyplot.
> xcorr(*args, **kwargs) > XCORR(x, y, normed=False, detrend=mlab.detrend_none, > usevlines=False, **kwargs): Sorry I'm not helping yet, but while you are in the middle of all this, please ditch the ugly and misleading Matlab-style capitalization of the function names. Thanks for all the work and amazing progress. Eric
On Friday 23 May 2008 6:06:30 pm Eric Firing wrote: > > xcorr(*args, **kwargs) > > XCORR(x, y, normed=False, detrend=mlab.detrend_none, > > usevlines=False, **kwargs): > > Sorry I'm not helping yet, but while you are in the middle of all this, > please ditch the ugly and misleading Matlab-style capitalization of the > function names. > > Thanks for all the work and amazing progress. Some of these docstrings are *really* hard to trace. Where does pyplot.arrow get its docstring? It looks like it comes from axes.arrow, which gets a bit from patches.FancyArrow, which gets a bit from patches.Patch, which gets a bit from artist.kwdocd['Patch'] at the top of patches.py. However, I have completely rewritten artist.kwdocd['Patch']: artist.kwdocd['Patch'] = """ ================= ============================================== Property Description ================= ============================================== alpha float animated [True | False] antialiased or aa [True | False] clip_box a matplotlib.transform.Bbox instance clip_on [True | False] edgecolor or ec any matplotlib color facecolor or fc any matplotlib color figure a matplotlib.figure.Figure instance fill [True | False] hatch unknown label any string linewidth or lw float lod [True | False] transform a matplotlib.transform transformation instance visible [True | False] zorder any number ================= ============================================== """ but the change has not propagated up to pyplot.arrow. I have to break here for the weekend, I'll be back monday afternoon. Leave some for me! (although I'll owe doughnut to whoever can fix the arrow docstring). Darren
On Fri, May 23, 2008 at 6:14 PM, Darren Dale <dar...@co...> wrote
> I have to break here for the weekend, I'll be back monday afternoon. Leave
> some for me! (although I'll owe doughnut to whoever can fix the arrow
> docstring).
I'll claim that doughnut.
This is a bit complicated. The problem is that we have to do the
interpolation into the patch doc strings at class definition time (eg
for Patch and Rectangle), but we can't use the object inspector and
doc string generator artist.kwdoc to automatically generate them until
*after* they are defined. So we have a bit of a race condition. The
solution, which is not terribly elegant, is to define the string for
the *classes* manually with the setting at the top of
matplotlib.patches:
artist.kwdocd['Patch'] = """\
alpha: float
animated: [True | False]
antiali
We interpolate this into the class docstrings. Once the classes are
defined, we can introspect the class and auto generate the strings for
use in *methods* that operate on class instances. At the bottom of
patches:
artist.kwdocd['Patch'] = patchdoc = artist.kwdoc(Patch)
artist.kwdocd['Patch'] = patchdoc = artist.kwdoc(Patch)
for k in ('Rectangle', 'Circle', 'RegularPolygon', 'Polygon',
'Wedge', 'Arrow',
'FancyArrow', 'YAArrow', 'CirclePolygon', 'Ellipse'):
artist.kwdocd[k] = patchdoc
so the changes you make in the kwdocd dict will affect the classes in
matplotlib.patches, bu will not affect the docstrings in the plotting
functions, eg matplotlib.axes.Axes.arrow, which will use the
auto-generated version from artist.kwdoc. So you need to make your
changes in two places: in the kwdocd dict at the top of patches, as
you did before, *and* in the artist.kwdoc function which
auto-generates the property tables. If this function returns rest
tables, you will be in good shape. It is not good design to have to
make the changes in two places, but when we implemented this we could
not find a way to do the class doc string interpolation after the
class was defined, but we still wanted to use the autogenerated docs
where possible (eg in methods that handle artists like the plotting
methods) since the auto-generated stuff is more likely to remain
current.
Maybe an entry in the developer's guide is warranted....
Enjoy your vacation.
JDH
On May 25, 2008, at 12:13 PM, John Hunter wrote: > > I played around with this a bit this morning -- it may be too busy for > your OS X sensibilities, but let me know if you think think this is an > approach wotrh pursuing. I've added the mathtext background and a few > axes and there are a few more axes to do. In svn as > examples/api/logo2.py I must admit, I was a little worried when you suggested adding a big equation in the background, but I think you did a good job of making it look nice. Unfortunately, I get an error when I try to run the logo2 script: AttributeError: 'NoneType' object has no attribute 'get_ticklabels' module body in logo2.py at line 23 for label in ax.get_xticklabels() + ax.get_yticklabels(): If I comment-out that for-block, I run into another error: NotImplementedError: xlim not meaningful for polar axes module body in logo2.py at line 43 ax.set_xlim(-2*sigma, 2*sigma) I'm guessing the first error is a trunk vs. v0_91_maint issue? Is the second a naming error in the commit? Maybe axhist.set_xlim instead of ax.set_xlim? Overall I really like the new logo, but I'd like play around with it a bit for kicks. Thanks! -Tony
On Sun, May 25, 2008 at 11:50 AM, Tony Yu <ts...@gm...> wrote: > I must admit, I was a little worried when you suggested adding a big > equation in the background, but I think you did a good job of making it look > nice. Unfortunately, I get an error when I try to run the logo2 script: I'm not wed to it, so just experiment. > AttributeError: 'NoneType' object has no attribute 'get_ticklabels' > module body in logo2.py at line 23 > for label in ax.get_xticklabels() + ax.get_yticklabels(): > If I comment-out that for-block, I run into another error: > NotImplementedError: xlim not meaningful for polar axes > module body in logo2.py at line 43 > ax.set_xlim(-2*sigma, 2*sigma) > I'm guessing the first error is a trunk vs. v0_91_maint issue? Is the second You need to be on the trunk and I think I was a commit behind -- try it now. We will probably want to set the various ticklabel and title sizes to something really small using rc import matplotlib matplotlib.rcParams['xtick.labelsize'] = 6 so that we can tweak all these in one place at the top of the script. JDH
On May 25, 2008, at 1:01 PM, John Hunter wrote: > > You need to be on the trunk and I think I was a commit behind -- try > it now. > > We will probably want to set the various ticklabel and title sizes to > something really small using rc > > import matplotlib > matplotlib.rcParams['xtick.labelsize'] = 6 Unfortunately, I'm not running the trunk right now because I use numpy 1.0.4 (not 1.1). I played around with the script, but in the process I ended up rewriting it a bunch. I'm sure I've violated come coding guidelines along the way; my apologies.
I'll be working on converting docstrings to rest this weekend. Should any of this be done on the branch? Or should we just focus on the trunk?
On Sat, May 31, 2008 at 9:19 AM, Darren Dale <dar...@co...> wrote: > I'll be working on converting docstrings to rest this weekend. Should any of > this be done on the branch? Or should we just focus on the trunk? As far as I am concerned, the documentation effort is for the trunk. The only reason to do them on the branch too is to make merges of other code changes easier, which may be a compelling reason. If the docstrings get far out of whack, it may make merging other changes very painful. But at the same time, I don't want the burden of trying to keep the two in sync stopping you from getting the work done that you need to do. Maybe you can try it and see how hard it is, and if proves to be too much of an impediment, just concentrate on the trunk. Michael, any advice here? JDH
On Saturday 31 May 2008 12:36:11 pm John Hunter wrote: > On Sat, May 31, 2008 at 9:19 AM, Darren Dale <dar...@co...> wrote: > > I'll be working on converting docstrings to rest this weekend. Should any > > of this be done on the branch? Or should we just focus on the trunk? > > As far as I am concerned, the documentation effort is for the trunk. I would really prefer to concentrate on the trunk. There's enough work as it is. Darren
On Friday 23 May 2008 7:54:27 pm John Hunter wrote:
> On Fri, May 23, 2008 at 6:14 PM, Darren Dale <dar...@co...>
> wrote
>
> > I have to break here for the weekend, I'll be back monday afternoon.
> > Leave some for me! (although I'll owe doughnut to whoever can fix the
> > arrow docstring).
>
> I'll claim that doughnut.
When was the last time you received one in the mail?
(more at the end...)
> This is a bit complicated. The problem is that we have to do the
> interpolation into the patch doc strings at class definition time (eg
> for Patch and Rectangle), but we can't use the object inspector and
> doc string generator artist.kwdoc to automatically generate them until
> *after* they are defined. So we have a bit of a race condition. The
> solution, which is not terribly elegant, is to define the string for
> the *classes* manually with the setting at the top of
> matplotlib.patches:
>
> artist.kwdocd['Patch'] = """\
> alpha: float
> animated: [True | False]
> antiali
>
> We interpolate this into the class docstrings. Once the classes are
> defined, we can introspect the class and auto generate the strings for
> use in *methods* that operate on class instances. At the bottom of
> patches:
>
> artist.kwdocd['Patch'] = patchdoc = artist.kwdoc(Patch)
>
> artist.kwdocd['Patch'] = patchdoc = artist.kwdoc(Patch)
> for k in ('Rectangle', 'Circle', 'RegularPolygon', 'Polygon',
> 'Wedge', 'Arrow',
> 'FancyArrow', 'YAArrow', 'CirclePolygon', 'Ellipse'):
> artist.kwdocd[k] = patchdoc
>
> so the changes you make in the kwdocd dict will affect the classes in
> matplotlib.patches, bu will not affect the docstrings in the plotting
> functions, eg matplotlib.axes.Axes.arrow, which will use the
> auto-generated version from artist.kwdoc. So you need to make your
> changes in two places: in the kwdocd dict at the top of patches, as
> you did before, *and* in the artist.kwdoc function which
> auto-generates the property tables. If this function returns rest
> tables, you will be in good shape. It is not good design to have to
> make the changes in two places, but when we implemented this we could
> not find a way to do the class doc string interpolation after the
> class was defined, but we still wanted to use the autogenerated docs
> where possible (eg in methods that handle artists like the plotting
> methods) since the auto-generated stuff is more likely to remain
> current.
>
> Maybe an entry in the developer's guide is warranted....
Thanks for the detailed explanation. I'm tagging the message so I can remember
to include it in the developers guide. Now that I understand it, it wasn't
too difficult to reformat the output into a ReST table. Onwards!
Darren
On Saturday 31 May 2008 4:14:39 pm Darren Dale wrote: > On Saturday 31 May 2008 12:36:11 pm John Hunter wrote: > > On Sat, May 31, 2008 at 9:19 AM, Darren Dale <dar...@co...> > > wrote: > > > I'll be working on converting docstrings to rest this weekend. Should > > > any of this be done on the branch? Or should we just focus on the > > > trunk? > > > > As far as I am concerned, the documentation effort is for the trunk. > > I would really prefer to concentrate on the trunk. There's enough work as > it is. I made some pretty good progress today. I found the source of that error that was causing sphinx to fail without a helpfull message, there was a ********* in the contour documentation. pyplot_api is about halfway converted, there are only 60 warnings reported by sphinx for pyplot. I just realized, though, that I should probably be striving to conform with the standard that the numpy and scipy folks put together: http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines and http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py . Any comments? I think I have been relying too heavily on tables for the keyword arguments. Darren
Hey folks,
I'm super excited about this, so I decided to give it a quick test run
with current trunk SVN. Running ./make.py in the doc/ directory
worked for a while, and then stalled at:
Sphinx v0.3, building latex
trying to load pickled env... done
building [latex]: all documents
updating environment: 0 added, 0 changed, 0 removed
processing Matplotlib.tex... index users/index users/pyplot_tutorial
users/mathtext users/navigation_toolbar users/customizing
users/artists users/event_handling faq/index faq/installing_faq
faq/troubleshooting_faq faq/howto_faq devel/index devel/coding_guide
devel/documenting_mpl devel/add_new_projection api/index
api/artist_api api/pyplot_api
resolving references...
writing... Exception occurred:
File "/home/fperez/usr/local/lib/python2.5/site-packages/Sphinx-0.3-py2.5.egg/sphinx/latexwriter.py",
line 479, in visit_entry
raise NotImplementedError('Column or row spanning cells are '
NotImplementedError: Column or row spanning cells are not implemented.
The full traceback has been saved in /tmp/sphinx-err-l_Oadi.log, if
you want to report the issue to the author.
Please also report this if it was a user error, so that a better error
message can be provided next time.
Send reports to sph...@go.... Thanks!
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
%&-line parsing enabled.
entering extended mode
! I can't find file `Matplotlib.tex'.
<*> Matplotlib.tex
Please type another input file name:
I don't know if you are so in the middle of things that you'd rather
not get bug reports on this for a while. If that's the case I'll wait
until the dust settles a bit.
In any case, many thanks for pushing this doc effort forward! The
overall usability of the combined tools, in a few months, is going to
really be massively improved thanks to all this common focus on
sphinx-based docs.
Cheers,
f
On Sat, May 31, 2008 at 9:01 PM, Fernando Perez <fpe...@gm...> wrote:
> I don't know if you are so in the middle of things that you'd rather
> not get bug reports on this for a while. If that's the case I'll wait
> until the dust settles a bit.
Well, we definitely want our docs to build so we're happy to get the
feedback -- sometimes it's a simple matter of a dev forgetting to
commit a critical file. I am getting this error too. It appears to
be a bug in the pyplot docstrings -- Darren, perhaps you haven't
committed all you recent changes? But if I remove entirely the pyplot
api doc which is causing this problem, I get lots of other errors
along the lines of those shown below. Is this a latex or sphinxext
config error?
[8 <./pyplot_formatstr.png> <./pyplot_three.png>] [9] [10]
<pyplot_two_subplots.png, id=368, 578.16pt x 433.62pt>
<use pyplot_two_subplots.png> <use pyplot_two_subplots.png> [11 <./pyplot_two_s
ubplots.png>] <pyplot_text.png, id=375, 578.16pt x 433.62pt>
<use pyplot_text.png> <use pyplot_text.png> [12 <./pyplot_text.png>] [13]
[14]
Chapter 2.
[15] [16]
! Undefined control sequence.
<recently read> \mathbb
l.954 \end{tabulary}
?
! Undefined control sequence.
<recently read> \mathcircled
l.954 \end{tabulary}
...and lots more like this....
JDH
On Mon, May 26, 2008 at 1:50 PM, Tony Yu <ts...@gm...> wrote: > I played around with the script, but in the process I ended up rewriting it > a bunch. I'm sure I've violated come coding guidelines along the way; my > apologies. And I made several changes -- mainly to simplify the logo. My wife thought it looked busy, and she has better taste than I do, so I stripped it down a bunch and added the many small subplots as a sidebar on the right. Let me know what you think and don't be shy about being critical despite Darren's kind sensitivities. I don't take pride in my graphic design abilities and so will happily make changes See http://matplotlib.sf.net for the new logo(s) and the attached for the stripped down script. JDH
On Sat, May 31, 2008 at 3:19 PM, Darren Dale <dar...@co...> wrote: Darren> I have to break here for the weekend, I'll be back monday afternoon. Darren> Leave some for me! (although I'll owe doughnut to whoever can fix the Darren> arrow docstring). John> I'll claim that doughnut. Darren> When was the last time you received one in the mail? Well, I remember the last time quite clearly, when Perry sent me a doughnut in the mail from Maryland to settle a "dollars-to doughnuts" bet. Unfortunately, I can't remember the subject of the bet right now (Perry?), though I kept the doughnut in my freezer, in the addressed envelope, for many months as a souvenir. JDH
I'm not sure either, it was something simple like having problems building and John suggesting that I blow away the previous installation. But I indeed did eventually mail the doughnut. Perry On May 31, 2008, at 10:35 PM, John Hunter wrote: > On Sat, May 31, 2008 at 3:19 PM, Darren Dale > <dar...@co...> wrote: > > Darren> I have to break here for the weekend, I'll be back monday > afternoon. > Darren> Leave some for me! (although I'll owe doughnut to whoever > can fix the > Darren> arrow docstring). > > John> I'll claim that doughnut. > > Darren> When was the last time you received one in the mail? > > Well, I remember the last time quite clearly, when Perry sent me a > doughnut in the mail from Maryland to settle a "dollars-to doughnuts" > bet. Unfortunately, I can't remember the subject of the bet right > now (Perry?), though I kept the doughnut in my freezer, in the > addressed envelope, for many months as a souvenir. > > JDH
On Sat, May 31, 2008 at 7:50 PM, Darren Dale <dar...@co...> wrote: > I just realized, though, that I should probably be striving to conform with > the standard that the numpy and scipy folks put together: > http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines and > http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py . Any comments? I > think I have been relying too heavily on tables for the keyword arguments. I think that following their guidelines is a good idea for the most part, but we needn't adhere to them religiously. For one thing, matplotlib uses *a lot* more keyword args than either numpy or scipy, and what works for them for kwargs may not be best for us. In particular, if we use the format they suggest, I'm afraid our docstrings will simply take up too much space. For example, see http://mentat.za.net/numpy/refguide/functions.xhtml#all-a-axis-none-out-none . What if we formatted all the Line2d kwargs that way? It seems a bit bloated in terms of vertical space for the number of kwargs we need to handle, and so a ReST table may in fact be better. We want our documentation to be mostly consistent to aid the folks trying to put together bits and pieces of documentation from several projects to write in-house docs (which incorporate local docs) or books, but I'm not sure we need our doc formatting to be entirely consistent at the API level. JDH
On Saturday 31 May 2008 10:45:34 pm John Hunter wrote: > On Sat, May 31, 2008 at 7:50 PM, Darren Dale <dar...@co...> wrote: > > I just realized, though, that I should probably be striving to conform > > with the standard that the numpy and scipy folks put together: > > http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines and > > http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py . Any comments? > > I think I have been relying too heavily on tables for the keyword > > arguments. > > I think that following their guidelines is a good idea for the most > part, but we needn't adhere to them religiously. For one thing, > matplotlib uses *a lot* more keyword args than either numpy or scipy, > and what works for them for kwargs may not be best for us. In > particular, if we use the format they suggest, I'm afraid our > docstrings will simply take up too much space. For example, see > http://mentat.za.net/numpy/refguide/functions.xhtml#all-a-axis-none-out-non >e . What if we formatted all the Line2d kwargs that way? It seems a bit > bloated in terms of vertical space for the number of kwargs we need to > handle, and so a ReST table may in fact be better. I agree. We should default to parameter lists, but longer lists of kwargs will be formatted as tables. There are also some features in the numpy template (like the use of sections) that cause sphinx to fail. I wonder how the webpage you referenced was generated? > We want our documentation to be mostly consistent to aid the folks > trying to put together bits and pieces of documentation from several > projects to write in-house docs (which incorporate local docs) or > books, but I'm not sure we need our doc formatting to be entirely > consistent at the API level. Right, we shouldn't worry about rigorously adhering to a standard, but their template seems like a good guideline to keep in mind.
Hi all I only read this thread today, and see that we have been battling many of the same challenges in our documentation efforts. I am glad to see that you are making such good progress! 2008年6月1日 John Hunter <jd...@gm...>: >> I just realized, though, that I should probably be striving to conform with >> the standard that the numpy and scipy folks put together: >> http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines and >> http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py . Any comments? I >> think I have been relying too heavily on tables for the keyword arguments. > > I think that following their guidelines is a good idea for the most > part, but we needn't adhere to them religiously. For one thing, > matplotlib uses *a lot* more keyword args than either numpy or scipy, > and what works for them for kwargs may not be best for us. In > particular, if we use the format they suggest, I'm afraid our > docstrings will simply take up too much space. For example, see > http://mentat.za.net/numpy/refguide/functions.xhtml#all-a-axis-none-out-none > . What if we formatted all the Line2d kwargs that way? It seems a > bit bloated in terms of vertical space for the number of kwargs we > need to handle, and so a ReST table may in fact be better. I'd like to explain the rationale behind our approach. Our main focus was to write produce documentation that is easy to read from a text-based terminal. While designing our standard, we set aside all other concerns, such as markup, compatibility with existing tools, etc. After the standard was more-or-less finalised, we wrote a tool which parses docstrings into logical units. For example, In [5]: d = SphinxFunctionDoc(np.ravel) In [6]: d['Parameters'] Out[6]: [('a', '{array_like}', ['']), ('order', "{'C','F'}, optional", ["If order is 'C' the elements are taken in row major order. If order", "is 'F' they are taken in column major order."])] In [7]: print d **ravel(a, order='C')** ----------------------- Return a 1d array containing the elements of a (copy only if needed). [...] Note that, when printing the docstring, it looks entirely different from the original docstring, and contains customised markup. If you wanted to use a table to describe keyword arguments, for example, it would require only a few extra lines of code. If you are interested in playing with the code, it is available at https://code.launchpad.net/~stefanv/scipy/numpy-refguide We also developed a web-framework that allows our community to write documentation: http://sd-2116.dedibox.fr/pydocweb While it was written with NumPy in mind (we have some weird docstring injection, not unlike yours), it should be trivial to modify for use by another project. Good luck! Stéfan
On Saturday 31 May 2008 10:19:47 pm John Hunter wrote: > On Sat, May 31, 2008 at 9:01 PM, Fernando Perez <fpe...@gm...> wrote: > > I don't know if you are so in the middle of things that you'd rather > > not get bug reports on this for a while. If that's the case I'll wait > > until the dust settles a bit. > > Well, we definitely want our docs to build so we're happy to get the > feedback -- sometimes it's a simple matter of a dev forgetting to > commit a critical file. I am getting this error too. It appears to > be a bug in the pyplot docstrings -- Darren, perhaps you haven't > committed all you recent changes? All my changes had already been committed. I had only been creating html (./make.py html) and it looks like some of the tables I have been creating dont agree with latex. I'll fix it tomorrow, but in the meantime, please just make html. > But if I remove entirely the pyplot > api doc which is causing this problem, I get lots of other errors > along the lines of those shown below. Is this a latex or sphinxext > config error? Not sure, I'll look into it on Sunday as well. Cheers, Darren
On May 31, 2008, at 10:30 PM, John Hunter wrote: > > And I made several changes -- mainly to simplify the logo. My wife > thought it looked busy, and she has better taste than I do, so I > stripped it down a bunch and added the many small subplots as a > sidebar on the right. I agree, the stripped down logo looks much better. > Let me know what you think and don't be shy > about being critical despite Darren's kind sensitivities. I don't > take pride in my graphic design abilities and so will happily make > changes > > See http://matplotlib.sf.net for the new logo(s) and the attached for > the stripped down script. I like the new color scheme on the website. Since you asked for criticism, though, I'm not a fan of the blue "matplotlib" in the logo (on the website, the attached logo is actually different). I think black or a dark gray looks better (color=[0.2, 0.2, 0.2]). Or, if you prefer blue, something less like the default hyperlink color (e.g. color=[.1,.1,.5]). My 2 cents. BTW, I noticed that website is a little old (pure HTML, no CSS). If you're ever interested in redesigning the website (nothing fancy, mainly just moving to CSS), I'd be happy to help out. -Tony > JDH > <logo2.png>