Hi all, This last Friday I had a chance to talk to Tom Abel and Oliver Hahn (both CC'd on this message) about their experiences with using yt, and they brought up some points which I've now had a chance to think about, and which I find very interesting, certainly as something to discuss. Here are my notes on it, along with a proposal for moving forward. As a quick note, what really hit home that we need better documentation was trying to make a thin projection. The definition of what a 'source' could be wasn't there, there were no examples, and I had to go look at the source to figure out what the parameters were even called. I think that's not ... good. Python Inline Documentation =========================== One of the coolest things about Python is the help() function, which prints out the function signature and the contents of the doc string. In the source code, the docstring is inline in the function, like so: def some_function(a, b, c): """ This function does something. """ return a+b+c The output of help(some_function) would look like this:
help(some_function) Help on function some_function in module __main__:
some_function(a, b, c) This function does something.
Generated Documentation ======================= The yt docs are generated using an extension to Sphinx called autodoc. What this does, as you can see by going to the API docs and clicking "view source" (which, counterintuitively, displays the doc source and not the source code of the functions) is at documentaion build time, pull all the docstrings from the source and render them in the document. Ideally, we would want something that renders nicely as well as looks good in the inline help -- and to maximize the detail without becoming encumbering. For most of the functions in yt that have docstrings, they have been written in a narrative style, with parameters inside asterisks, so that they would render nicely in the API docs: http://yt.enzotools.org/doc/modules/amrcode.html#yt-lagos-outputtypes-output... But, it's becoming clear that perhaps this is not the best approach. I think a combination of narrative and explicit parameter declaration would be better. The NumPy/SciPy projects have a CodingStandards description: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines that covers docstrings, with a very detailed example of a completely filled out docstring here: http://svn.scipy.org/svn/numpy/trunk/doc/example.py As an example, the 'tensorsolve' function is defined here: http://svn.scipy.org/svn/numpy/trunk/numpy/linalg/linalg.py and the API docs are here: http://docs.scipy.org/doc/numpy/reference/generated/numpy.linalg.tensorsolve... This looks great, I think. yt is a bit more class-oriented than NumPy, but I believe that we should strive for a similar level of detail as well as a similar style: presenting parameters, what those parameters can be, and a brief word on the return type. Ideal Type Of Documentation =========================== A few weeks ago, Tom and I were chatting and he mentioned to me a Pascal manual. In this manual, there was a single function on every page: a description, parameters (often repeated between functions, but explicitly listed for each), and an example. My first Unix manual was exactly like this, and I remember it being one of the best sets of documentation I've ever used. I believe this is the model NumPy and SciPy are striving for, as well. I think this is what yt should strive for, too. One page per class or function, with a description, parameters, and examples -- just like mentioned above. In doing so, I think that the online help -- which right now is sort of helpful, but not amazingly helpful, would become much more useful. The fact that on the mailing lists we get questions asking us about fundamental operations in yt is, I think, an indictment of the way it's presented. As the Enzo Workshop revs up, a couple of us will be writing talks about using Enzo, using yt, etc, and I think this is a time to harness that momentum to reorganize and rewrite some of the doc strings. Of course, I would take the lead on the initial rewrite, as I'm the one who wrote all the bad docstrings. What does everyone think about this? Action Items ============ (It wouldn't be a long email about procedures if we didn't use a buzzword like 'action items' :) Firstly: a vote and a request for comments. Do we want to agree on the NumPy standard for docstrings? What does everyone think about this idea, of a set of docstring guidelines, and trying to focus on a better set of API documentation, to be used both in generated form and inline via help()? If we can agree on the NumPy standard, I believe that I should be able to convert most of the docstrings with some relative ease; it's mostly going to be a matter of typing, copy/pasting, etc. I will copy a style guide into doc/, which will be largely taken from the NumPy style guide, but I will additionally add a document with examples for common strings: I would prefer we have a single, consistent manner for referring to things like AMR3DData as a source, for instance. I will then go through and convert all the doc strings that I am familiar with. This would leave us with three files: * Example docstring, which can be read in verbatim and edited. * List of yt idioms for cross-referencing and describing things. * File describing this standard, largely pulling from the NumPy standard. The next thing will be, going forward, how do we ensure that the doc strings are correctly inserted with new code? I am more guilty of this than I would care to admit (I sometimes fall into the camp of thinking that functions with well-named parameters are self-documenting, which is probably a mistake!) but I think having someone agree to review incoming changesets for documentation updates, and then to email the committer if they do not have a sufficient docstring. My inclination is to suggest that someone who already reviews incoming changesets to do this, which I think means either me, Sam or Stephen. Sam, would you be willing to take this on? It should be relatively straightforward. Additionally, would anyone volunteer to help me out with rewriting some of the existing docstrings? In particular, for code you have contributed? The End ======= I think that if we really take the docstrings seriously, then the documentation on the whole will vastly improve. I am in the process of rewriting some sections, removing the old-style tutorial and trying to better walk the user through the process of getting up and running. The current documentation has a lot of information, but it's not very good at getting people up and running in anything other than the most simple manner. I think that getting started on improving the docstrings will also help refocus efforts toward better documentation on the whole. And, I'd like to end by admitting culpability for the sorry state of the docstrings we currently have. But I think this might be good, in the long run, because it'll help out with getting us on track for a better code that's much easier to use! And finally, thanks to Tom and Oliver for taking the time to chat with me about this -- I really appreciate their thoughtful feedback on this. Best, Matt
Hi all, First of all let me say that I'm a fan of moving to more complete docstrings. As Matt said, the help() or ? capability in python is really a great feature that makes it easy to explore an analysis/computation package and has been crucial for me with packages such as numpy, matplotlib, scipy, etc. I think that if we were to move to a standardized format for the docstrings both beginning and advanced users of yt would also benefit. For example, if you pull up the help on pc.add_slice, one gets: In [4]: ?pc.add_slice Type: instancemethod Base Class: <type 'instancemethod'> String Form: <bound method PlotCollection.add_slice of <yt.raven.PlotCollection.PlotCollection object at 0x1047dcdd0>> Namespace: Interactive File: /Library/Frameworks/Python.framework/Versions/2.6/lib/python2.6/site-packages/yt-2.0dev-py2.6-macosx-10.6-i386.egg/yt/raven/PlotCollection.py Definition: pc.add_slice(self, *args, **kwargs) Docstring: Generate a slice through *field* along *axis*, optionally at [axis]=*coord*, with the *center* attribute given (some degeneracy with *coord*, but not complete), with *use_colorbar* specifying whether the plot is naked or not and optionally providing pre-existing Matplotlib *figure* and *axes* objects. *fig_size* in (height_inches, width_inches) This is tricky because we have moved to *args, **kwargs for the arguments, and then the docstring does not explain what the args, kwargs are. Explicitly listing the arguments along with their types and a quick description would be invaluable to new users. As for the format of the docstrings, I am fine with the NumPy standard. I would suggest that whatever the standard becomes that there be a boilerplate example that can just be copied into any new function where developers can edit where necessary, and stick this example somewhere like the doc folder. I'm thinking of something like: """ DESCRIPTION CAVEATS Parameters ---------- ARG : TYPE ARG_DESCRIPTION KWARG : TYPE, optional KWARG_DESCRIPTION Returns ------- VAL : TYPE Raises ------ ERROR ERROR_CASE. See Also -------- OTHER_FUNCTIONS Examples -------- >>> SETUP >>> EXECUTE >>> SHOW_RESULTS """ This should help reduce the overhead in properly documenting newly written functions. Finally, since I do seem to read the majority of commits coming in, I'd be happy to be the guy to remind someone when their docstrings aren't up to snuff. Cheers, Sam On Sun, May 30, 2010 at 4:18 PM, Matthew Turk <matthewturk@gmail.com> wrote:
Hi all,
This last Friday I had a chance to talk to Tom Abel and Oliver Hahn (both CC'd on this message) about their experiences with using yt, and they brought up some points which I've now had a chance to think about, and which I find very interesting, certainly as something to discuss. Here are my notes on it, along with a proposal for moving forward.
As a quick note, what really hit home that we need better documentation was trying to make a thin projection. The definition of what a 'source' could be wasn't there, there were no examples, and I had to go look at the source to figure out what the parameters were even called. I think that's not ... good.
Python Inline Documentation ===========================
One of the coolest things about Python is the help() function, which prints out the function signature and the contents of the doc string. In the source code, the docstring is inline in the function, like so:
def some_function(a, b, c): """ This function does something. """ return a+b+c
The output of help(some_function) would look like this:
help(some_function) Help on function some_function in module __main__:
some_function(a, b, c) This function does something.
Generated Documentation =======================
The yt docs are generated using an extension to Sphinx called autodoc. What this does, as you can see by going to the API docs and clicking "view source" (which, counterintuitively, displays the doc source and not the source code of the functions) is at documentaion build time, pull all the docstrings from the source and render them in the document. Ideally, we would want something that renders nicely as well as looks good in the inline help -- and to maximize the detail without becoming encumbering.
For most of the functions in yt that have docstrings, they have been written in a narrative style, with parameters inside asterisks, so that they would render nicely in the API docs:
http://yt.enzotools.org/doc/modules/amrcode.html#yt-lagos-outputtypes-output...
But, it's becoming clear that perhaps this is not the best approach. I think a combination of narrative and explicit parameter declaration would be better. The NumPy/SciPy projects have a CodingStandards description:
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
that covers docstrings, with a very detailed example of a completely filled out docstring here:
http://svn.scipy.org/svn/numpy/trunk/doc/example.py
As an example, the 'tensorsolve' function is defined here:
http://svn.scipy.org/svn/numpy/trunk/numpy/linalg/linalg.py
and the API docs are here:
http://docs.scipy.org/doc/numpy/reference/generated/numpy.linalg.tensorsolve...
This looks great, I think. yt is a bit more class-oriented than NumPy, but I believe that we should strive for a similar level of detail as well as a similar style: presenting parameters, what those parameters can be, and a brief word on the return type.
Ideal Type Of Documentation ===========================
A few weeks ago, Tom and I were chatting and he mentioned to me a Pascal manual. In this manual, there was a single function on every page: a description, parameters (often repeated between functions, but explicitly listed for each), and an example. My first Unix manual was exactly like this, and I remember it being one of the best sets of documentation I've ever used. I believe this is the model NumPy and SciPy are striving for, as well.
I think this is what yt should strive for, too. One page per class or function, with a description, parameters, and examples -- just like mentioned above. In doing so, I think that the online help -- which right now is sort of helpful, but not amazingly helpful, would become much more useful.
The fact that on the mailing lists we get questions asking us about fundamental operations in yt is, I think, an indictment of the way it's presented. As the Enzo Workshop revs up, a couple of us will be writing talks about using Enzo, using yt, etc, and I think this is a time to harness that momentum to reorganize and rewrite some of the doc strings. Of course, I would take the lead on the initial rewrite, as I'm the one who wrote all the bad docstrings.
What does everyone think about this?
Action Items ============
(It wouldn't be a long email about procedures if we didn't use a buzzword like 'action items' :)
Firstly: a vote and a request for comments.
Do we want to agree on the NumPy standard for docstrings? What does everyone think about this idea, of a set of docstring guidelines, and trying to focus on a better set of API documentation, to be used both in generated form and inline via help()?
If we can agree on the NumPy standard, I believe that I should be able to convert most of the docstrings with some relative ease; it's mostly going to be a matter of typing, copy/pasting, etc. I will copy a style guide into doc/, which will be largely taken from the NumPy style guide, but I will additionally add a document with examples for common strings: I would prefer we have a single, consistent manner for referring to things like AMR3DData as a source, for instance. I will then go through and convert all the doc strings that I am familiar with. This would leave us with three files:
* Example docstring, which can be read in verbatim and edited. * List of yt idioms for cross-referencing and describing things. * File describing this standard, largely pulling from the NumPy standard.
The next thing will be, going forward, how do we ensure that the doc strings are correctly inserted with new code? I am more guilty of this than I would care to admit (I sometimes fall into the camp of thinking that functions with well-named parameters are self-documenting, which is probably a mistake!) but I think having someone agree to review incoming changesets for documentation updates, and then to email the committer if they do not have a sufficient docstring. My inclination is to suggest that someone who already reviews incoming changesets to do this, which I think means either me, Sam or Stephen. Sam, would you be willing to take this on? It should be relatively straightforward.
Additionally, would anyone volunteer to help me out with rewriting some of the existing docstrings? In particular, for code you have contributed?
The End =======
I think that if we really take the docstrings seriously, then the documentation on the whole will vastly improve. I am in the process of rewriting some sections, removing the old-style tutorial and trying to better walk the user through the process of getting up and running. The current documentation has a lot of information, but it's not very good at getting people up and running in anything other than the most simple manner. I think that getting started on improving the docstrings will also help refocus efforts toward better documentation on the whole. And, I'd like to end by admitting culpability for the sorry state of the docstrings we currently have. But I think this might be good, in the long run, because it'll help out with getting us on track for a better code that's much easier to use!
And finally, thanks to Tom and Oliver for taking the time to chat with me about this -- I really appreciate their thoughtful feedback on this.
Best,
Matt _______________________________________________ Yt-dev mailing list Yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
-- Samuel W. Skillman DOE Computational Science Graduate Fellow Center for Astrophysics and Space Astronomy University of Colorado at Boulder samuel.skillman[at]colorado.edu
Hi Sam,
This is tricky because we have moved to *args, **kwargs for the arguments, and then the docstring does not explain what the args, kwargs are. Explicitly listing the arguments along with their types and a quick description would be invaluable to new users.
Agreed. In fact, that *specific* example is one I intend to get rid of: http://yt.enzotools.org/ticket/242 But yes, where kwargs are unavoidable, they should be explicitly listed in the docstring.
As for the format of the docstrings, I am fine with the NumPy standard. I would suggest that whatever the standard becomes that there be a boilerplate example that can just be copied into any new function where developers can edit where necessary, and stick this example somewhere like the doc folder.
Yes, definitely. I intend to not only include a fiducial example like the NumPy docs, but also a list of helpful mechanisms for cross-referencing between objects, as well as idioms for describing common patterns.
Finally, since I do seem to read the majority of commits coming in, I'd be happy to be the guy to remind someone when their docstrings aren't up to snuff.
Great, thanks! -Matt
Hi, all-- I fully agree with using the Numpy standard. I have a few additions to that, and then another point to bring up. The numpy standard says that the "description" should not reference the variables. I don't think this is strictly necessary, especially since we have narrative descriptions for a lot of functions already. I like the Big List Of Functions that's available on the Numpy docs. It makes "Dang, there has to be a function that does X but I don't know what it's called" much much easier. I would find this kind of thing useful in the yt docs, as well. The numpy docs do a pretty good job of "you might also like" for each function. While this is somewhat more difficult to do, as it takes a pretty global understanding of the code base, it's quite useful. For instance, I had been using h.find_max and h.find_min separately, when h.all_data().quantites['Extrema'] does exactly what I want. This brings me to my other point-- classes, and class inheritance hierarchies. I don't have any good solutions, but I feel that this is one aspect of yt that isn't really well addressed by the Numpy standard, and bears discussion. Even their class suggestions are still pretty 1d and procedural, whereas the hierarchy structure in yt is more like a 3d data space: class/derived class/ method. When one wants to perform an action, you need not only the method, but the correct object to act upon, and as in the find_min vs. Extrama, there may be multiple options for both. Python is only ok about auto documenting methods and members and inheritence resolution for classes. help() on an object or an instance of the object gives some useful things, like method resolution, and some of the methods inherited and from which super class. However, this still leaves a bunch to be desired. For instance, (and this might be my own ignorance) doing
help( pf.h )
doesn't show anything about the availability of pf.h.covering_grid or AMRCovering grid. It also makes the Big Ol' List O' Functions more difficult, or perhaps simply requires a "list by method name" and "list by class" option... My own inexperience with other heavily OOP documentations leaves me without another example that I like (matplotlib is class heavy, but the documentation also leaves a lot to be desired) but I know that some of you are pretty sharp, so might have good suggestions. Those are my thoughts right now. d. On Tue, Jun 1, 2010 at 8:44 AM, Matthew Turk <matthewturk@gmail.com> wrote:
Hi Sam,
This is tricky because we have moved to *args, **kwargs for the arguments, and then the docstring does not explain what the args, kwargs are. Explicitly listing the arguments along with their types and a quick description would be invaluable to new users.
Agreed. In fact, that *specific* example is one I intend to get rid of:
http://yt.enzotools.org/ticket/242
But yes, where kwargs are unavoidable, they should be explicitly listed in the docstring.
As for the format of the docstrings, I am fine with the NumPy standard. I would suggest that whatever the standard becomes that there be a boilerplate example that can just be copied into any new function where developers can edit where necessary, and stick this example somewhere like the doc folder.
Yes, definitely. I intend to not only include a fiducial example like the NumPy docs, but also a list of helpful mechanisms for cross-referencing between objects, as well as idioms for describing common patterns.
Finally, since I do seem to read the majority of commits coming in, I'd be happy to be the guy to remind someone when their docstrings aren't up to snuff.
Great, thanks!
-Matt _______________________________________________ Yt-dev mailing list Yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
-- Sent from my Stone Tablet and carried by my Pterodactyl.
Hi, I just want to briefly make a few extra comments, though I won't add much to the already excellent discussion. First, I vote for the Numpy standard as well. However, I think Dave raises a very important point: dealing with the multidimensional nature of OOP documentation will be the biggest challenge. I have recently gone through and documented a very large, extremely object oriented code base (entirely for my own benefit, as I was the only novice user at the time). I found one of the biggest challenges in OOP is the notion of multiple entry points to various objects and their connection to one another (inheritance, especially). I don't really have a solution to the problems Dave mentions, but perhaps if we are clear about return values and can provide some way of linking input parameters to their objects, that might help a lot toward a "if you like this, why don't you try that" style. As a side note, not only does the help(pf.h) not reveal much information about class relationships, in iyt In [1]: pf.h? returns nothing even remotely useful. This is definitely something that needs resolution, as there is a growing number of interactive yt users coming from idl-land who may think there is no on-line help if ? fails. Like Tom and Matt, I had a great experience with an early manual typeset with one thing per page. This is a great idea, and I think we can improve it by setting out some kind of entry point for large yt concepts. For example with matplotlib, I always start with something like fig = figure() ax = fig.add_axis([0.1,0.1,0.8,0.8]) and that axis object is my entry point to nearly the entire plot. If we had something that was somewhere in between an API doc and the manual at large that gave a few starting points and then linked to the API doc for that entry point, perhaps that might help some. j
Hi Jeff, everyone else, Okay. I think we are in large agreement about a couple things we want, and a couple things that are problematic, which I'll try to summarize here. * The Numpy docstring standard is useful. Adhering to some variant of this, possibly with a narrative string that includes variable names, is a good idea. * Cross-referencing between objects is essential. This means that we need to have a canonical "DataSource" reference in docstrings for everything that accepts a 1-, 2- or 3-D data source, for instance. * Implicit in Jeff's comment above about pf.h? not returning anything useful is actually something that should be handled: overloading of methods is hard to document. As of right now, if you have a data object like a sphere, it's completely unmentioned in the documentation that you can do sphere["Density"] and get back Density. * The idea of starting points is super interesting, and one I think that needs to be explored. * We need a Big List Of Functions, which might also include "Big List Of Data Sources", "Big List Of Quantities", "Big List Of Fields" and "Big List Of Callbacks." * The current mechanism for generating data sources ("pf.h.something(...)"), which made sense when it was first implemented, doesn't necessarily help us in the problem of getting info from docstrings. * We need to be more aggressive in documenting things from a programmatic standpoint. I'd like to quickly point out that Stephen Skory has really been great with writing narrative documentation for his contributions. * Single-page-per-function docs are fun, and I am going to try to implement that immediately, so that we can all see how poorly set up the docstrings are as of right now. ;-) Related to this, I'm going to ditch the disqus comments at the bottom of every page of the docs -- we've had zero so far, and the more I think about it the less useful it seems to me even if people *were* to comment. Perhaps this idea of entry points and roads is a way to move: we can provide entry points to objects, and then show people roads to other objects. I'm just about ready at this point to scrap most of the documentation that I've written and start anew, but unfortunately that's a daunting task. Documenting is not only hard to sit down and do ... but it's hard to get right. I know that when I write documentation, I bring with me my knowledge and preconceptions about how things can and should be done, and that gets in the way of laying down a thread that goes from "Simulation" to "Plots." I remember, I forget if it was Brian O'Shea or Britton Smith that said this, but someone told me back in 2008, "There are two types of things you can do with yt. 'Things you can do with yt', and 'Things you can do with yt if you're Matt.'" I'd thought we'd gotten away from that, but the abject failure of the online documentation and the inability of the existing narrative documentation to take a user and move them from Beginner to (even) Intermediate has begun to indicate to me that we have not. If you go to http://yt.enzotools.org/doc/ right now, the table of contents is ridiculously long, largely because of the cookbook. I think that it should be substantially stripped down, and I'm going to propose a new table of contents, which I'll do my best to flesh out. (This will also be the outline of my workshop tutorial, I think.) * Introduction (move Jeff's "Analysis Philosophy" section here) * Installing and Starting Up * Just Looking At Some Data: new and revised introduction, no real advanced stuff, nothing but meaty walkthrough * Cookbook * Intermediate and Advanced yt: less narrative, more discussion of some underlying components like profiles, projections, extracted regions * Extensions: this section will probably be moved, as-is * Contributing Code * Asking for Help * FAQ * YT Methods * API Docs: this is where we will have the many-many-pages of API docs, hopefully organized relatively well. I'll have a stab at this today or soon. * Changelog Anyway, I think maybe that would be an improvement ... but I'm not sure I am yet on the right track. Any thoughts or suggestions? Thanks, everyone, for your helpful ideas and discussion. I think these kind of discussions are important, because they help us to re-evaluate the public facing side of a code we're all contributing to and that we can all be proud of. -Matt On Thu, Jun 3, 2010 at 5:34 PM, j s oishi <jsoishi@gmail.com> wrote:
Hi,
I just want to briefly make a few extra comments, though I won't add much to the already excellent discussion. First, I vote for the Numpy standard as well. However, I think Dave raises a very important point: dealing with the multidimensional nature of OOP documentation will be the biggest challenge. I have recently gone through and documented a very large, extremely object oriented code base (entirely for my own benefit, as I was the only novice user at the time). I found one of the biggest challenges in OOP is the notion of multiple entry points to various objects and their connection to one another (inheritance, especially). I don't really have a solution to the problems Dave mentions, but perhaps if we are clear about return values and can provide some way of linking input parameters to their objects, that might help a lot toward a "if you like this, why don't you try that" style.
As a side note, not only does the help(pf.h) not reveal much information about class relationships, in iyt
In [1]: pf.h?
returns nothing even remotely useful. This is definitely something that needs resolution, as there is a growing number of interactive yt users coming from idl-land who may think there is no on-line help if ? fails.
Like Tom and Matt, I had a great experience with an early manual typeset with one thing per page. This is a great idea, and I think we can improve it by setting out some kind of entry point for large yt concepts. For example with matplotlib, I always start with something like
fig = figure() ax = fig.add_axis([0.1,0.1,0.8,0.8])
and that axis object is my entry point to nearly the entire plot. If we had something that was somewhere in between an API doc and the manual at large that gave a few starting points and then linked to the API doc for that entry point, perhaps that might help some.
j _______________________________________________ Yt-dev mailing list Yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
Hi-- tl:dr Let's make these lists:
* We need a Big List Of Functions, which might also include "Big List Of Data Sources", "Big List Of Quantities", "Big List Of Fields" and "Big List Of Callbacks."
I think that all of these Big Lists would be great. I would use them every day. I can help with docs on these, if you need.
* The current mechanism for generating data sources ("pf.h.something(...)"), which made sense when it was first implemented, doesn't necessarily help us in the problem of getting info from docstrings.
I think that the above Bigs Lists would go a long way to helping this. Perhaps we could stick a reference to the web page in the doc string of things we know are going to be problematic?
objects. I'm just about ready at this point to scrap most of the documentation that I've written and start anew, but unfortunately that's a daunting task. Documenting is not only hard to sit down and
I think all the existing docs are good, there definitely isn't anything that I would scrap. I think we just need to keep filling the parameter space of ways to use yt. Right now, I'm personally most interested in the Big Lists of Things, because I've read all the cook book pages, and the only documentation left is the source code. The source is pretty readable, but it takes much longer to get what I need that way. I think "Big Lists Of Stuff" should be the next push. I think if we start with the ones Matt mentioned, that would get us a long way. Quantities, fields, and callbacks are all pretty straight forward and can just follow the Numpy format. I think that the Big List of Data Sources will need more info. I'll think about a structure that would be useful for that. I would add those lists straight to your Table of Contents. I would like it if it were pretty high level. If you make the list, I can help with filling out the details. d.
Hi Dave,
I think that all of these Big Lists would be great. I would use them every day. I can help with docs on these, if you need.
I'd love some help on this.
I think that the above Bigs Lists would go a long way to helping this. Perhaps we could stick a reference to the web page in the doc string of things we know are going to be problematic?
Absolutely. And cross-referencing within docs is relatively easy, as well.
I think all the existing docs are good, there definitely isn't anything that I would scrap. I think we just need to keep filling the parameter space of ways to use yt. Right now, I'm personally most interested in the Big Lists of Things, because I've read all the cook book pages, and the only documentation left is the source code. The source is pretty readable, but it takes much longer to get what I need that way.
Okay, sounds good. I'm looking at how to get this new sphinx extension "viewcode" working, which should enable us to include the (highlighted) source directly in the doc builds.
I think "Big Lists Of Stuff" should be the next push. I think if we start with the ones Matt mentioned, that would get us a long way. Quantities, fields, and callbacks are all pretty straight forward and can just follow the Numpy format. I think that the Big List of Data Sources will need more info. I'll think about a structure that would be useful for that.
I've uploaded a first stab at this: http://yt.enzotools.org/doc/dev_build/ specifically, the API docs here: http://yt.enzotools.org/doc/dev_build/api/index.html It has nothing other than the docstrings -- I'm going to add descriptions to the individual module / conceptual pages as time goes on, but right now while auto-generating the splits from the original way modules were documented means it's still a bit in flux and I didn't want to have anything get lost. It took a little while to get the numpy doc extensions working with the latest Sphinx, but they should now be in there mostly correctly. I think this highlights just how bad our docstrings are right now ... I updated the FixedResolutionBuffer docstring, and using the autosummary directive the numpy docs will split everything up into subpages and so on. Here's the page describing the basics of plotting: http://yt.enzotools.org/doc/dev_build/api/plot_types.html and then if you go to the FRB page: http://yt.enzotools.org/doc/dev_build/api/generated/plot_types/yt.raven.Fixe... you can see where the methods are all documented and whatnot. Here's the source code, for reference: http://yt.enzotools.org/browser/trunk/yt/raven/FixedResolution.py#L29 Unfortunately, there are a bunch of artifacts in the other docstrings. I'm going to try to sketch out rough passes at some of the docstrings, but it's going to be a while before this is really ready for primetime. You can see how it has rendered a bunch of other things, too. I think maybe flattening the list a bit more could be helpful, but I'm just happy that the docstring parser and splitter is working. As a quick comment, it'll be easier to move around the larger organization and outline than it will be to split and unsplit pages and change the way the docstrings get divvied up. Thoughts on any of this? I think this is the closest we've come to having the single-function-per-page manual, which is becoming more and more appealing to me. :) -Matt
participants (4)
-
david collins -
j s oishi -
Matthew Turk -
Sam Skillman