sphinx severe: unexpected section title -- arbitrary headings in function docstring

Question

Using autodoc and similar tools allows one to compile documentation from source docstrings. It doesn't however, seem to allow arbitrary ReST section titles in function or class docstrings, and produces the error:

SEVERE: Unexpected section title.

I encoutered a similar problem when trying to document following the numpy style guidelines without numpydoc: unexpected section title with sphinx is numpy the issue and how does numpy process docstrings into sphinx documentation for parameters

Here however, I'm actually documenting JavaScript and would simply like to have arbitrary section titles and ReST in a docstring.

Javascript docstring api: sphinx jsapidoc

Answer 1

Yes, the requirement to add arbitrary section titles and ReST within a docstring can pose challenges; sphinx-jsapidoc is effective for this requirement.