sphinx-doc / sphinx-doc/sphinx

Conversion of docstring (probably but wrongly) triggers the reStructuredText formatter

Open
#6,853 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autosummary type:bug
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:

image

But sphinx's generated documentation does not:

image

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.