How to automatically populate documentation with %(before_notes)s and %(after_notes)s

Contributor & Development Discussion scipy
1

I have written a module for a research project that implements some probability distributions as subclasses of Scipy’s rv_continuous class. Now I would like to create some documentation for my module and I would like that documentation to be consistent with Scipy’s. I see that Scipy’s probability distribution docstrings (e.g. the one for scipy.stats.uniform here) use a dictionary to insert boiler-plate text and (I think) to generate examples automatically: %(before_notes)s, %(example)s, and %(after_notes)s.

As far as I can tell this dictionary is kept in scipy.stats._distn_infrastructure.py but I can’t see how to use it. How do I go about this? I am using Sphinx, of course.

2

You just use those %(before_notes)s, etc. markers in your docstring in the appropriate places, and you’re done. The rv_generic base class of rv_continuous will do the interpolation for you.

1 Like
3

So this doesn’t seem to work for me. I must be doing something wrong. Here’s a MWE. I have a standard package directory structure.

.
├── docs
│   ├── build
│   └── source
│       └── conf.py
├── my_package
│   └── __init__.py
└── setup.py

The my_package/__init__.py file contains the following.

import scipy as sp

__all__ = [
    "pdf"
]

class pdf_gen(sp.stats.rv_continuous):
    """A PDF docstring

    %(before_notes)s

    %(example)s

    %(after_notes)s

    """
    def _pdf(self, x):
        return x
    
pdf = pdf_gen(a=0., b=1., name="pdf")

Now if I install my_package, import it, and inspect its docstring (my_package.pdf.__doc__) then I see that the before_notes, example, and after_notes fields have been populated. But if I try to generate the documentation using Sphinx I see nothing. My docs/source/conf.py contains this:

import os
import sys
import my_package
sys.path.insert(0, os.path.relpath("../../my_package"))

project = 'my_package'

extensions = [
    "sphinx.ext.autodoc"
]

I run sphinx-api -o source ../my_package and make html from the docs directory but I see no docstrings in the module documentation. What’s going wrong?

4

Examine how we document the scipy.stats reference documentation. We use .. automodule: scipy.stats with a specific configuration underneath it (c.f. here), then use .. autosummary from sphinx.ext.autosummary in the scipy.stats docstring to explicitly list the objects that we want documented (in your example case, you would list the pdf object).

In any case, the %(before_notes)s etc. mechanism is not involved in whether or not it shows up in Sphinx; it’s already done it’s job by making pdf.__doc__ complete. Getting your Sphinx document configured to find and incorporate the pdf object is a separate matter.

1 Like
5

That’s solved it for me! Thank you so much for your help. I really appreciate it.