Questions tagged [docstring]
A docstring is a string that occurs as the first statement in a module, function, class, or method definition, and is used to document the object in which it occurs.
703
questions
0
votes
0
answers
27
views
Hide attributes from sphinx autodoc but show them in docstring
I want to do two things at once:
Display the attributes of a class in its docstring, so that, for example, it will available in a Jupyter notebook when I hit Shift + Tab + Tab.
However, in the Sphinx ...
0
votes
0
answers
30
views
Error mkdocstrings generation error "No module named"
I was building a documentation site for my python project using mkdocstrings.
For generating the code referece files I followed this instructions https://mkdocstrings.github.io/recipes/
I get these ...
0
votes
0
answers
27
views
How to remove function table auto generation in a class using docstrings with sphinx?
With docstrings and automodule in sphinx I can display documentation of a parent class and children methods like that:
As you can see, methods are displayed two times. Once in a table (under "...
0
votes
0
answers
51
views
How to display function docstrings from parent class with inheritance order display in Sphinx
With docstrings and automodule in sphinx I can display documentation of a parent class and children methods like that:
where Compute is a method of the above class.
I saw here: Attribute docstring ...
0
votes
0
answers
23
views
Python Docstring (numpy style) How to document ValueError raised for different reasons?
How do I document ValueError raised for different reasons in proper numpy style docstring?
For now after reading the docs I'm confused between:
Raises
------
ValueError
if reason1
if reason2
if ...
0
votes
1
answer
21
views
Is it possible to show __init_subclass__ docstring on the subclass?
Let's say I have a class that implement __init_subclass__ with two parameters:
class Foo:
def __init_subclass__(name: str, surname: str):
"""
name: The name of the ...
0
votes
0
answers
27
views
How to make docstrings from cythonized module available to Pylance?
I am working on a fully cython compiled python package, using setuptools and some reStructured Text docstrings to generate the pdf documentation using sphinx-autodoc with good success.
The docstrings ...
0
votes
0
answers
18
views
Inherit a function (incl. docstring) as a class method
Imagine, there is a function like this
def bar(a: str, b: str):
"""
Do somehting with a and b.
"""
print(a, b)
Then there is a class, where i would like ...
0
votes
0
answers
148
views
What is the cause of the Sphinx warning "Block quote ends without a blank line; unexpected unindent" in a one line docstring
When I build my Sphinx HTML documentation, I get a warning.
checkdmarc.py:docstring of checkdmarc.BIMIRecordInWrongLocation:1: WARNING: Block quote ends without a blank line; unexpected unindent.
...
0
votes
0
answers
24
views
AttributeError | How should I call a class method?
My class code in edit (For presentation, not a problem for my question.)
class TxtFile:
"""Responsible for the file.
Creates objects that store the text of a '.txt' file
"&...
1
vote
1
answer
44
views
How does "Insert documentation comment stub" work in Pycharm for getting method parameters?
I have enabled Insert documentation comment stub within Editor | General |Smart keys :
But then how to get the method parameters type stubs? Adding the docstring triple quotes and then enter does ...
0
votes
1
answer
48
views
What is the `current` correct format for Python Docstrings according to PEP standards?
I've been looking all over the web for the current standards for Python Docstrings and I've come across different answers for different scenarios. What is the currently most-accepted and wide-spread ...
0
votes
2
answers
44
views
Python: How is the docstring code running and is this the correct way to code a menu?
Errors for this codeI don't understand how the code under the docstring is running. I am trying to make a main menu. I also keep getting errors under the comments
def main_menu():
# Function for ...
0
votes
1
answer
86
views
scalafmt - docstrings conflict with significant indentation
The following piece of code:
class Test:
/** A very
* useful
* piece
* of
* documentation
*/
def helloWorld =
42 match
case 42 =>
a()
b()
/** A ...
2
votes
2
answers
122
views
Why does the function definition and doctring show twice when I hover over the function in VS Code? How to resolve to showing once?
On hovering the mouse pointer over a function, whether inbuilt or custom, the definition and docstring of the function shows as expected, however it shows twice. I have had a search for what might be ...
0
votes
1
answer
31
views
Is there any existing function to convert a docstring to dict?
Does anyone have the similar experience to print assigned information for different objects?
For instance, the following docstring printed from getattr(obj,'__doc__')
__doc__
Keyword arguments
--------...
0
votes
0
answers
116
views
Vscode not displaying python doc string properly
Just moved from pycharm to vscode and noticed something strange when i hover over functions , the doc string is not being displayed properly.
Attaching a snapshot of the docstring using a jupyter ...
0
votes
0
answers
29
views
Increase height, width of docstring in Jupyter notebook
When pressing Shift-Tab in Jupyter notebook, it pops-up docstring (help for the function). How can I change the docstring height/width to minimize scrolling? Currently, the pop-up window is so small ...
1
vote
2
answers
33
views
Print docstring with default --help function
I have a code that looks like:
#!/usr/bin/env python
'''Plot multiple DOS/PDOS in a single plot
run python dplot.py -h for more usage
'''
import argparse
import sys
import matplotlib.pyplot as plt
...
1
vote
1
answer
101
views
Automatically generate API reference for all subpackages / modules
I am using mkdocs with the mkdocstrings plugin to generate the documentation of my Python package.
My package is organized in a standard fashion
- setup.py
- mkdocs.yaml
- docs/
- mypackage/
- ...
-1
votes
1
answer
71
views
How to fix "Unexpected section title"? [duplicate]
This docstring:
"""
Returns
-------
out: int
Output.
Bad title
---------
Text.
"""
produces:
C:\module.py:docstring of my_pkg.module.func:5: CRITICAL: Unexpected ...
2
votes
1
answer
157
views
Proper way to document keys in TypedDict?
What is the proper way to document keys inside a TypedDict? I don't see much information inside PEP 589 – TypedDict.
I can think of a few solutions:
Document keys inside a docstring (is there a ...
0
votes
0
answers
24
views
Using docstrings with Cython - attribute not found in module error
I am trying to use documentation using docstrings- my code is written in cython and compiles fine normally
When I try to run
pdoc --http localhost:8080 main.pyx
I get a bunch of errors such as
module ...
0
votes
1
answer
60
views
Python docstrings broken, requires parameter first
I got a strange error using python's docstrings in combination with Sphinx Autodoc/Napoleon:
When using docstrings, the formatting is broken as soon as i put the comment above the parameters.
"&...
0
votes
1
answer
14
views
docstring of dynamic module attribute
I have dynamic module attributes, which are functools.partial constructor of the module's class (Filter). The attributes themselves work as intended, but if possible I'd like to improve how help ...
1
vote
1
answer
82
views
Pycharm docstring: How to add types into docstring with typing [duplicate]
In vscode, I install autoDocstring plugin, it can generate doc with types based on Typing. like below:
def split_dataset(
data: torch_geometric.data.Data,
train: float = 0.1,
...
-1
votes
1
answer
50
views
PEP8 best docstring practice when function has multiple different return [duplicate]
I have the following function:
def eg_fun(eg:int):
"""example function
"""
if eg > 2:
return 2, 4
else:
return 'no', None
In the ...
3
votes
0
answers
47
views
how to find the docstring in the numpy.random module?
I try to find the docstring of the numpy.random.random() function in vscode. To do this i can keep navigating to the definition using go to definition from the menu or by pressing the f12 key.
...but ...
1
vote
1
answer
28
views
Persistent cache during deployment with sphinx-autoapi?
I have been stuck with a problem for several days without solutions. I am trying to deploy local docs generated with Sphinx to Gitlab pages.
Below is my .gitlab-ci.yml on the root directory of the ...
0
votes
1
answer
270
views
How can I resolve flake8 error "D205: 1 blank line required between summary line and description"?
I'm trying to use flake8(pydocstyle) to check the quality of my docstring and I'm getting this error:
D205: 1 blank line required between summary line and description
This is how my code looks like
...
2
votes
1
answer
665
views
How to write docstring summary on multiple lines without triggering D205 and D400?
Say that I have
def foo()
"""This is the first part of the summary,
and this is the second part of the summary.
This is the description.
"""
I got both ...
0
votes
0
answers
42
views
How to document *args parameter for method? [Python]
How do document a method arguments using NumPy (PEP 257) convention when it contains *args parameter?
For example, I have such a method in my class:
def add_seis(self, *args, timeout=-1):
'''
...
0
votes
0
answers
160
views
".. note::" and ".. deprecated::" annotations are not recognized by PyCharm
I set my PyCharm to use reStructured docstring format, however it does not recognize .. note:: or .. deprecated::. And by that I mean when you hover over the method which has such annotations, it ...
-2
votes
1
answer
192
views
vim with python: [missing-function-docstring] Missing function or method docstring
I have vim 9.0 with Python support: I have auto complete and Syntax checking for Python installed. Here is my ~/.vimrc file contents:
set nocompatible " required
filetype off ...
1
vote
0
answers
64
views
How could I create a docstring decorator in the presence of properties?
I have a collection of ever more specialized classes which correspond to collections of the same kind of data (temperature, density, etc) but for different drifts, for example, one subclass has ...
0
votes
0
answers
96
views
Ruby yard documenting DSL method definition AND its uses>
Ruby with Yard 0.9.8.
I'm defining custom attribute accessors in a ClassMethods module that will be extended into classed and other modules.
What I want to do is document what the DSL accessor methods ...
1
vote
1
answer
194
views
How to read the docstring of test functions from a fixture?
I was trying to get the docstrings of all the test functions from a fixture defined in conftest.py, as shown in the code below, so that they can be analyzed for purposes.
But, from here how can I ...
0
votes
1
answer
108
views
how to make pybind11 property docstring to show up?
I have following code:
py::class_<Logger> logger(m, "Logger");
logger.doc() = "class docstring";
logger.def("setLevels", [](uint16_t levels)
{
...
0
votes
1
answer
59
views
How do you specify return type on a callable parameter with reST docstring?
Here's a working example with type hinting where I can annotate the parameter that it takes an int and a string and returns a boolean:
from typing import Callable
def func(another_func: Callable[[int,...
0
votes
1
answer
62
views
How to pass doc string into flask jinja html?
Is it ways to document my html template right from flask views like that?:
@app.route('/data_transcript', methods=['GET', 'POST'])
def data_transcript():
"""string for html template&...
0
votes
0
answers
48
views
find the doc string for builtins such as the "print" function
usually when i create a function in python, the doc string is written like this:
def some_function(n):
""" the docstring describing the function
inputs:
n (str): ...
2
votes
1
answer
279
views
Docstrings for overloaded functions with .. autofunction:: in Sphinx
I have an issue with using the Sphinx's .. autofunction:: directive on a function that has multiple @overload decorators.
While prototypes of the functions are included, the docstrings I want are not.
...
-1
votes
1
answer
1k
views
How to add link in Python docstring?
I have a function in python 3.x
def foo():
"""Lorem ipsum for more info, see here""
I want to add a hyperlink to 'here' to point to a website. How can I do that without ...
0
votes
0
answers
90
views
Indentations in Docstring
I am using Python 3.9.12 on Spyder 5.2.1.
I am trying to write a docstring as follows.
def readArray(parameters, key):
"""
NAME
readArray - Read an array from an input ...
1
vote
1
answer
105
views
Appending to inherited method docstring
I'm trying to define a subclass that only changes the __init__ method, that change will change the behavior of some of the methods and I wanted to be able to update the docstrings accordingly. I have ...
0
votes
0
answers
49
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:
&...
-1
votes
1
answer
23
views
Quantify docstrings in python project
Is there anyway to quantify the percentage of docstrings in a python project, concerning all modules, function, classes, methods, etc.?
I didn't found any package or linter offering that.
0
votes
1
answer
53
views
Why sphinx does not recognize some part of docstring
I would like to use sphinx for documenting a django project. All is fine when using sphinx.ext.autodoc. But I come accross some throuble with the following. The docstring under Parameters and Returns ...
1
vote
0
answers
134
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
2
answers
270
views
Python Docstring - two different types of arguments of a function
I tried to make my function-description look beautiful but it didn't work. The problem is that I have two types of returns: a list and a string. Then you hover on functions vscode shows the returns of ...