Make Python API documentation a little more user-friendly

[paulromano]

The Python API docs are currently pretty barebones. We should spruce them up with a little more commentary and some IPython notebook examples.

[paulromano]

434 added two IPython notebooks and beefed up the index page for the Python API. We should certainly do more (e.g., add module docstrings, add more notebooks) but for now we can consider this closed.

[wbinventor]

I hope to contribute some more Notebooks to our collection of examples over time. It would be cool if we could "crowd-source" a bit and pull in some Notebooks from those users out there who may be using the Python API. I recognize that GitHub is the perfect pathway for this, but I feel that our users are typically removed from the day-to-day conversation on here (this may be more a reflection on the nuclear community than anything).

The module docstrings is of course something to keep in mind for the near future. It would also be nice to include some "Example" blocks in our docstrings (like this). But perhaps most valuable would be a cohesive set of tutorials, akin to the Notebooks I created for our students at MIT who use PINSPEC for reactor physics coursework. I can't commit to taking on this endeavour at the moment, but we shall see.

Finally, it might be worthwhile to refer those who are still writing XML by hand to the Python API with a link from the User's Guide. What do you think

[paulromano]

Agreed! All great ideas. Examples in method docstrings would be very useful for quickly seeing how it's used without actually going to the notebooks. I'll leave this issue open with no milestone so we don't forget about it.

[wbinventor]

Yeah, I think it is a good idea to keep it open. Docstring examples and the like would really make it much easier to use the API documentation. Not to set the bar too high, but I think that a reach goal would be to develop documentation like that in scikit-learn (which is albeit a much, much larger and widely used code than OpenMC, but one of the best documented Python packages out there IMHO).

[wbinventor]

I think we have improved tremendously in this area over the last six months, most recently with PR #626. As I have been using Pandas and scikit-learn (sklearn) - two of the most widely used Python packages for data analysis outside of the "core" ecosystem of NumPy, SciPy and Matplotlib - I've come across a couple of niceties in their documentation that we may want to include in a "TODO" list for the future:

• [x] Links to source code. The scikit-learn package includes "[source]" links throughout it's documentation on class methods and attributes (see example here), which can be extremely useful.
• [ ] More examples. The scikit-learn package uses figures to link to their examples as shown here. We might turn the most striking figure from example into a link to a corresponding Jupyter Notebook.
• [ ] Downloadable notebooks. Although our Jupyter Notebook examples are proving to be very useful to both new and experienced users alike, one cannot download them directly from the website. Instead, one must know where to find them in the "docs/source/pythonapi/examples" directory. It would be nice to include a "download" link for each one to make this easy for new users.
• [ ] Video Tour. There are lots of video tutorials for both Pandas and Scikit-Learn. A short "best of" video tour like the one for Pandas here might be nice to bring the API down to ground level for new users.

I'm not volunteering to do any of these in the next few months, but thought I'd record a few observations based on my recent experience working with pandas and sklearn.

[wbinventor]

Another idea:

• [ ] Link to RTD. Based on some recent conversations with developers/users here in CRPG, few are aware that RTD exists, which is likely the case for non-MIT developers. A link on our website would be nice to inform those who are on the "develop" branch where to go for up-to-date docs.

[wbinventor]

I'll add to this my vote to move the links to the example Jupyter Notebooks on here to the top of the Python API page. They are likely where users should start in order to understand how to compose the objects and methods described in the API documentation.

[wbinventor]

Another thing we could do to simplify/shorten our documentation would be to use the Material.add_nuclide(...) and Material.add_element(...) methods championed by @smharper.

[paulromano]

@wbinventor Regarding the last comment, are you referring to our example notebooks specifically?

[wbinventor]

Both the notebooks as well as the scripts in "examples/python". The one advantage of leaving things as they are is that it highlights the object-oriented nature of Nuclides and Elements, but we don't really take much advantage of that at the moment.

[wbinventor]

We can also use the Materials.add_materials(...) convenience method in place of multiple calls to Material.add_material(...). A similar convenience method for Tallies.add_tallies(...) would be helpful too. All in the name of reducing the number of lines in our examples.

[paulromano]

Alternatively we can make a Materials.materials property that is a CheckedList.

[wbinventor]

I'm fine with that as long as it's well documented. I've expressed my concerns about CheckedLists before (i.e., it's may not be as obvious how to add items to a collection for new users). But this should be a non-issue if new users start from our examples in the first place (as I believe is the case from what I can tell).

[paulromano]

Or another option: make Materials list-like itself, so you could have:

fuel = openmc.Material()
water = openmc.Material()
boyd = openmc.Material()
romano = openmc.Material()

ms = openmc.Materials((fuel, water))
ms.append(boyd)
ms += [romano]

Come to think of it, allowing an iterable of materials to be passed to the constructor is probably the easiest and most non-controversial change to make.

[wbinventor]

Oh nice, I like that idea!