Hi there, I've been trying to take the numpy docstring and apply the same methodology to a different project I work on, but there are a couple details that I think I'm unclear on, and I was hoping for some pointers or at least reassurances that it's working as intended, despite Sphinx's protests. The process of applying the numpy docstring method seems to take a few steps: 0) Have sphinx >=1.0 installed. 1) Write a numpydoc-compliant docstring in a class and its methods. 2) Make available to sphinx the numpydoc extension (in this case, I am using the current numpy git tip, which self-reports as 0.4) 3) Add the sphinx.ext.autosummary and numpydoc extensions to conf.py in the appropriate sphinx project 4) Copy the autosummary/class.rst template to the appropriate _template directory in the sphinx project 5) Set up the autosummary_generate variable in conf.py to contain all the files containing autosummary directives. 6) Build docs As a few other quick notes, my reading of the overridden class.rst template is that it comments out the individual method inclusions, using the HACK (comment) directive. The build mostly proceeds correctly when these steps have been taken, but a copious number of warnings are emitted. (The same character of warnings are emitted by the numpy documentation build.) These mostly show up, for instance, as: WARNING: toctree contains reference to nonexisting document 'reference/api/generated/add_phase_object' In this case, add_phase_object is a method hanging off an autosummary'ed class. It looks like a warning gets emitted for every method on every autosummary'ed class -- this can number into the thousands very easily. Additionally, warnings that look like: reference/api/generated/yt.visualization.api.PlotCollection.add_phase_object.rst:: WARNING: document isn't included in any toctree show up, where these reflect the full method name and class name. It looks like the toctree is gaining references to the method names without prefixing them with the class names, but the generated docs all have the full name resolution in their filenames. (There also seems to be a glitch in the output when using the ".. HACK" class.rst template, as within my code it appears to strip the one-line descriptions from the methods.) Is this behaving as expected, or have I perhaps gone through the steps wrong? Having so many warnings can confuse debugging other portions of the build. I appreciate any suggestions you might have -- thanks very much! Best, Matt
participants (1)
-
Matthew Turk