sphinx-doc / sphinx-doc/sphinx
Conversion of docstring (probably but wrongly) triggers the reStructuredText formatter
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
I maintain the pyvinecopulib package and my docstrings are not properly converted by sphinx. Essentially, doing import pyvinecopulib as pv and help(pv.Bicop.loglik), I get:
help(pv.Bicop.loglik):
| loglik(...)
| loglik(self: pyvinecopulib.Bicop, u: numpy.ndarray[float64[m, n]] = array([], shape=(0, 2), dtype=float64)) -> float
However, the doc generated by sphinx appears as loglik(self, u, n]] = array[, dtype]). I have plenty of similar examples, but essentially, both the argument type and default value does not seem to work properly.
Steps to reproduce the behavior:
git clone --recursive https://github.com/vinecopulib/pyvinecopulib.git
cd pyvinecopulib
git checkout dev
pip install .
cd docs
make html
Then open _build/html/_generate/pyvinecopulib.Bicop.html.
The docstring appears correctly:

But sphinx's generated documentation does not:

Is it possible that conversion of the docstring (probably but wrongly) triggers the reStructuredText formatter somewhere? Or any idea what could be the issue?
Note that the docstrings were automatically generated by pybind11 and that I used
pv.doc() = R"pbdoc(
The pyvinecopulib package
-------------------------
.. currentmodule:: pyvinecopulib
.. autosummary::
:toctree: _generate
BicopFamily
bicop_families
Bicop
FitControlsBicop
Vinecop
FitControlsVinecop
CVineStructure
DVineStructure
RVineStructure
)pbdoc";
in my main.cpp file (where pv is the name of the module).
Also, my conf.py has
import sphinx_rtd_theme
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.intersphinx',
'sphinx.ext.autosummary',
'sphinx.ext.napoleon',
"sphinx_rtd_theme"
]
autosummary_generate = True
to generate automatically what is needed. I have replicated the issue on 2 different versions of Ubuntu and one Mint install.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the issue in the pyvinecopulib documentation setup with sphinx.ext.autodoc, autosummary, and napoleon by running the listed install and make html steps. Compare the generated _build/html/_generate/pyvinecopulib.Bicop.html with help(pv.Bicop.loglik) and determine why the pybind11-generated argument types and defaults are altered; done when the generated documentation preserves them.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100