64
questions
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 ...
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 ...
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 ...
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 ...
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....
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 ...
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, ...
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:
&...
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
...
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 ...
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', ...
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 ...
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 ...
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[...
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 ...
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::
:...
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 ...
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 ...
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 ...
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 ...
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
...
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 ...
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[]
...
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 ...
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\` ...
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/...
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
"""
...
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
...
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 ...
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:...
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 ...
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 : ...
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 ...
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 ...
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 ...
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 ...
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 ...
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 ...
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
...
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 ...
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 ...
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 ...
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 ...
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 ...
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 = ...
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
...
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 ...
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 ...
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 ...
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, ...