Skip to main content
Filter by
Sorted by
Tagged with
1 vote
2 answers
305 views

Understanding the Use of "Two Dots" in Python Docstrings

I'm currently in the process of learning about Python docstrings, particularly in the context of Google-style, NumPy-style, and Sphinx-style formatting. I've noticed that sometimes there are two dots ...
Patrickliu's user avatar
0 votes
1 answer
56 views

Can I prevent sphinx numpydoc to split the Returns into two sections

When using Sphinx Numpy doc. I document the Returns section. Returns ------- out: float A sentence about the return type However, rendered this is split into two sections. Returns: out - A ...
Hielke Walinga's user avatar
0 votes
1 answer
100 views

Dynamically substitute any Sphinx references

Summary of the Issue I am using a fork of a popular package, scikit-learn, (yes I need a fork for specific technical reasons) that has a documentation hosted with Sphinx. I want to simultaneously use ...
ajl123's user avatar
  • 1,252
0 votes
0 answers
75 views

Sphinx parent class in another package: how to disable single backtick reference warnings

I am working on implementing a Python package that inherits from networkx. Networkx seems to use numpydoc, but also wraps certain parts of their docstrings in single backtick characters: `. This ...
ajl123's user avatar
  • 1,252
0 votes
0 answers
396 views

Display directly first element of Sphinx index.rst's toctree instead of a blank page

I have a Python package (https://github.com/frannerin/AlloViz)'s documentation (https://alloviz.readthedocs.io/) with the following structure: AlloViz/docs/source │ conf.py │ index.rst │ README....
Francho Nerín Fonz's user avatar
5 votes
0 answers
579 views

Sphinx and Read the Docs not using NumPy docs style

I documented some modules of a Python package I wrote using NumPy style, and I set up a readthedocs website to host the automatically generated documentation (with sphinx.ext.napoleon). Despite trying ...
Francho Nerín Fonz's user avatar
0 votes
0 answers
193 views

sphinx (numpydoc) syntax warnings showing up in wrong file using vscode

In my docs/source/conf.py file, I have the numpydoc extension enabled, and it's generally working, except I'm getting docstring errors from different python files showing up as being caused in line 1, ...
DilithiumMatrix's user avatar
3 votes
1 answer
284 views

numpydoc: Can I omit the type declaration in the docstring when I use type hints?

When using type hints in the function signature, do I need to specify the parameter types in the docstring, too, if I were to comply with numpydoc style? def add(a: float, b: int) -> float: &...
Andi's user avatar
  • 4,425
2 votes
1 answer
400 views

Sphinx hiding modules imported in __init__.py

My package has a structure, similar to the following: ├── README.md ├── __init__.py ├── module1 │ └── submodule1.py │ └── submodule2.py ├── module2 │ ├── __init__.py │ ├── _hiden_submodule1.py ...
Liris's user avatar
  • 1,481
0 votes
0 answers
105 views

docstring codeblock not showing properly in spyder 5.2.21

I'm trying to comment my python function that I have written, according to sphinx and numpy docstring. Spyder uses sphinx to render the docstring in the help window. When I see my docstring in window ...
Ptiji's user avatar
  • 1
0 votes
0 answers
532 views

Sphinx Module Docstring Command Line Parameters/Argparse

What is the standard sphinx docstring format for module command line parameters? For example: if __name__ == '__main__': parser = argparse.ArgumentParser() parser.add_argument('-f', '--file', ...
Hersh Joshi's user avatar
5 votes
2 answers
738 views

Sphinx documentation showing double-colon in fields

I am developing documentation for a package and when I build the sphinx docs I'm getting double colons for all of the fields for every function definition. I am using the numpydoc style for my ...
Nick Roach's user avatar
1 vote
1 answer
238 views

Furo Sphinx theme keeps uppercasing too much in API documentation

I am facing the same problem discussed in this question: Furo Sphinx theme uppercases too much in API documentation. However, the accepted solution did not work, it seems that the Furo template is ...
Paulo Araujo's user avatar
1 vote
1 answer
119 views

Python: document property to specify type

Let's consider the following example: from typing import Union import numpy as np class MyClass: def __init__(self): self._x = None @property def x(self) -> Union[...
mauro's user avatar
  • 562
3 votes
0 answers
1k views

Sphinx doesn't inherit docstring from parent class

There are a lot of questions here on SO asking how to avoid inheriting the docstring of the parent when building docs with sphinx. I have the opposite problem: I want my class-level docstring to be ...
FirefoxMetzger's user avatar
0 votes
0 answers
195 views

Get autosummary to produce a flat representation

If I have a file foo.baz.py: from foo.bar.baz import Quux, Quuux __all__ = ['Quux', 'Quuux'] I'd like to document the api as follows: Baz === .. currentmodule:: foo.baz .. autosummary:: :...
oulenz's user avatar
  • 1,244
0 votes
1 answer
3k views

How to configure Sphinx autodoc to document classes in __init__.py?

I have Python codes with NumPy docstrings. Manage to use Sphinx for the API documentation, however, classes in the __init__.py file not documented successfully. Example: xxx/__init__.py from ...
CarolL's user avatar
  • 81
3 votes
1 answer
941 views

Using array-like as a type in napoleon without warning

I have a project with some functions documented in the napoleon numpy style. In the spirit of numpyness, I have a bunch of function arguments that are of the class array-like. Here is an example: def ...
Mad Physicist's user avatar
13 votes
3 answers
7k views

sphinx warning: autosummary: stub file not found for the methods of the class. check your autosummary_generate settings

I have an open source package with lots of classes over different submodules. All classes have methods fit and transform, and inherit fit_transform from sklearn. All classes have docstrings that ...
Sole Galli's user avatar
  • 1,007
0 votes
1 answer
387 views

Numpydoc how to document the signature of a function as an argument

I have the function def foo(bar): return bar(var1, var2) where bar is a function that takes two variables named var1 and var2 and returns an str obj, what is the proper numpydocs way to document ...
Tomergt45's user avatar
  • 659
6 votes
1 answer
1k views

Why do definitions have a space before the colon in NumPy docstring sections?

Numpy docstring guide says: The colon must be preceded by a space, or omitted if the type is absent. and gives an example: Parameters ---------- x : type Description of parameter `x`. y ...
hans's user avatar
  • 1,125
3 votes
1 answer
381 views

Is there a method for displaying plots after plt.show() with sphinx or keep scope after .. plot::

I am using sphinx with numpydocs, doctest, and the scipy theme. When using .. plot:: in a docstring, the plots are all created, except instead of showing where they are called, they all move to the ...
001001's user avatar
  • 568
4 votes
1 answer
2k views

How to type a list of int in numpydoc

What is the correct way to type a list of int in a numpydoc docstring. Is this syntax int[] for example valid ? def my_function(numbers): """ Parameters ---------- numbers : int[] ...
johannchopin's user avatar
  • 14.8k
3 votes
2 answers
3k views

Pycharm warning: Class 'Iterable' does not define '__getitem__'

I have recently been learning python and I was trying out some things in Pycharm when I noticed the following warning caused by this piece of code: Class 'Iterable' does not define '_getitem_', so ...
Demophilus's user avatar
1 vote
1 answer
155 views

Numpydoc style convention when returning an instance of a class

I'm following the numpydoc style guide to document my code but I cannot find the convention for returning an instance of a class : """Create an index in the meilisearch API. If the argument \`uid\` ...
Bidoubiwa's user avatar
  • 960
3 votes
0 answers
375 views

Sphinx and Numpydoc throws parse error when inheriting from third party package

I'm trying to use Sphinx and numpydoc to document my code, yet very unsuccessfully so far. When I m trying to make html I get this very confusing error: Exception occurred: File "/Users/...
Micromegas's user avatar
  • 1,669
2 votes
1 answer
295 views

How to get the same output from sphinx napoleon and numpy style docs as with the default rst way?

If I take the very simple python file: def magic_function(parameter1): """ Do magic with parameter1. :param parameter1: The first of all paramters :type parameter1: nd_array """ ...
NOhs's user avatar
  • 2,820
0 votes
1 answer
273 views

Broken format while using numpydoc and sphinx

I'm using sphinx with numpydoc extension. when I make html, every last item in my 'Examples' paragraph is broken. This is what I try to make document : """ ... Examples ...
LegenDUST's user avatar
  • 142
8 votes
1 answer
3k views

How to document multiple return values in Numpydoc format?

I am trying to document a tuple return value using numpy docstring format, but can't make it work with pycharm type hinting. I have tried multiple ways, and even found one that was working for the ...
Sebastien De Varennes's user avatar
0 votes
0 answers
758 views

Write power of 2 in sphinx documentation

I try to write power of 2 but I get something strange. def cal_xy(X, Y): """ Parameters ---------- X : np.ndarray, shape=(2\ :sup:`n`, 2\ :sup:`n`) Y : np.ndarray, shape=(2\ :sup:...
hamster on wheels's user avatar
1 vote
1 answer
571 views

Sphinx not removing doctest flags in html output

I cannot eliminate the doctest flags (ie. <BLANKLINE>, # doctest: +ELLIPSIS) for the html output. I am able to generate the documentation as I would like, so no errors there but it includes ...
dshanahan's user avatar
  • 734
8 votes
1 answer
2k views

Can mypy check docstrings?

I have numpydoc-style docstrings: def foobar(filename, copy, dtype, iterable, shape, files): """ foobar is 42. Parameters ---------- filename : str copy : bool dtype : ...
Martin Thoma's user avatar
1 vote
1 answer
7k views

Python auto docstring with sphinx new line

I am wondering how can I have a new line when generating auto documentation using Sphinx. I am not using the default Sphinx docstring format reStructuredText, but I am using the Numpydoc format. I ...
Kernel's user avatar
  • 653
4 votes
1 answer
939 views

How to properly document properties with NumpyDoc

I'm managing a package which uses the NumpyDoc style, and I'm trying to properly document the setters/getters of some properties. In particular, I'm having an issue with the fact that the ...
Jonas Adler's user avatar
  • 10.7k
8 votes
1 answer
3k views

Is it possible to have a list for a parameter in sphinx.ext.napoleon?

I'm using sphinx autodoc extension together with sphinx.ext.napoleon. I'm following numpydoc style guide since I think it is more readable than google's one. However, I've noticed the following issue ...
math's user avatar
  • 1,948
1 vote
1 answer
422 views

label in python docstring

I'm using sphinx autodoc to translate my docstring to a nice documentation page. In the docstring I'm following numpy's docstring guideline by using the sphinx napoleon extension. I'm wondering about ...
math's user avatar
  • 1,948
2 votes
1 answer
865 views

Does \r stand for something in sphinx?

I'm writing my docstring following the numpy docstring guidelines. Then I use sphinx's autodoc to generate my documentation. Within some docstrings I'm using LaTeX formulas (sphinx.ext.mathjax). It ...
math's user avatar
  • 1,948
3 votes
0 answers
586 views

Can py.test test docstring for the numpy style?

My pytest.ini currently looks like this: [pytest] addopts = --doctest-modules --cov=. --cov-report html --pep8 --flakes doctest_encoding = utf-8 So I already test for PEP8. But I would also like to ...
Martin Thoma's user avatar
6 votes
1 answer
9k views

WARNING: toctree contains reference to nonexisting document error with Sphinx

I used the sphinx-quickstart to set everything up. I used doc/ for the documentation root location. The folder containing my package is setup as: myfolder/ doc/ mypackage/ __init__.py ...
magnoliafork's user avatar
16 votes
1 answer
3k views

Is there any way to lint a Python file to check for Numpy documentation style adherence? [closed]

I'm working on a project that requires Numpy documentation. In my Java days, I remember having linters that checked for Javadoc adherence in Eclipse/IDEA; is there an equivalent that checks for Numpy ...
Mark Bao's user avatar
  • 906
11 votes
2 answers
1k views

List of class methods with Napoleon Sphinx extension using NumPyDoc style

I am using NumPyDoc-style docstrings to document a Python package. I would like to switch from the 'numpydoc' Sphinx extension to Napoleon, because I find that it formats the docstring in a more ...
Pietro Marchesi's user avatar
3 votes
1 answer
101 views

Verify code and documentation match

Using Sphinx extension NumpyDoc, is there some way to automatically make sure that the documentation matches the code it's documenting? For example, the following documentation does not match the ...
Seanny123's user avatar
  • 9,206
5 votes
1 answer
3k views

autosummary “toctree contains reference to nonexisting document” warnings

I am facing the same problem as in this thread. When I build my Sphinx documentation with make html then I get a lot of warnings like this None:None: WARNING: toctree contains reference to nonexisting ...
mr.bjerre's user avatar
  • 2,779
10 votes
1 answer
4k views

Bullet Lists after Paragraph in Python Docstring sometimes don't work with sphinx and numpydoc

Documenting a Python module using the numpy style and generating html documentation using sphinx and the numpydoc extension, I stumbled upon a bug (or feature?) regarding bulleted lists. In ...
Finwood's user avatar
  • 3,941
7 votes
2 answers
5k views

Autosummary with toctree not creating documentation for methods

I'm using sphinx with the numpydoc extension and autosummary. After some experimentation, I added the following options to my conf.py file. autosummary_generate = True numpydoc_show_class_members = ...
kesmit's user avatar
  • 121
9 votes
1 answer
3k views

How can I parse a numpydoc docstring and access components?

I'd like to parse a numpydoc docstring and access each component programatically. For example: def foobar(a, b): '''Something something Parameters ---------- a : int, default: 5 ...
caring-goat-913's user avatar
1 vote
1 answer
863 views

numpydoc conventions: method modifies class but returns nothing

Question about numpydoc docstring conventions: I have a class that contains a number of methods that return nothing, but add an attribute to the class. For example: class MyClass(object): def ...
oscarbranson's user avatar
  • 4,037
7 votes
1 answer
1k views

How can I use intersphinx with Tensorflow and numpydoc?

The main question here is where (if) there is an objects.inv for TensorFlow, but an example how to actually use it would be nice. For example, I currently have the following docstring: """ Load the ...
Martin Thoma's user avatar
16 votes
1 answer
2k views

Difference between sphinxcontrib.napoleon and numpy.numpydoc [closed]

I am writing documentation for a Python project using Numpy-style docstrings. numpydoc and napoleon are two Sphinx extensions that parse Numpy-style docstrings to generate documentation. The first ...
ndou's user avatar
  • 1,168
8 votes
1 answer
4k views

How does 'autodoc_default_flags' work in python Sphinx configuration?

I am trying to generate documentation for my python classes using Sphinx 1.4 and sphinx-apidoc and the sphinx.ext.autodoc extension. I have a lot of modules and I want each to only show class names, ...
sgt_pats's user avatar
  • 181