777 questions
0
votes
0
answers
17
views
Docstring formatting not working in VSCode
Minor issue. Some days ago, docstrings would be formatted so that when I hover over them, "Args" (Google-style) and "Returns" would be in bold, as well as the names of the ...
- 613
0
votes
0
answers
18
views
VSC Intellisense not parsing Sphynx docstrings
If i press ctrl+space on a function with a Sphinx formatted docstring
def example_function(param1: int, param2: str) -> bool:
"""
Processes data.
:param param1: The first ...
- 164
0
votes
0
answers
69
views
Is there a shortcut for python docstring to document implicit raised exception?
I'm working on a few python modules whose methods (by design) don't catch exceptions from functions called in their bodies. As far as I understand the results of my research, you should document any ...
- 426
0
votes
0
answers
37
views
Problem in the formatage of a doctest using numpy matrix
Let us assume that I have code in Python a function f taking one numpy matrix parameter.
I do not understand why the following doctest succeed
>>> f(U) - np.matrix([[ 2.31162781, 1.82477741, ...
- 61
0
votes
1
answer
45
views
Julia docstring gets replaced
I make the following module:
module Foo
export Bar
"""
Bar
Struct bar docstring.
"""
struct Bar
n::Int
@doc """
Bar(n::Int)
...
- 655
0
votes
1
answer
37
views
Why is a docstring sufficient to satisfy a python's definition of a function when its body is empty?
I discovered this fun feature of Python, where this:
def do_nothing():
"""Does nothing."""
is the same as this:
def do_nothing():
...
I found someone commented this here:
...
0
votes
0
answers
65
views
How to render numpy docstring nicely in VSCode?
I am working on a Python utilities library for parsing output generated by an external simulation program we use (called MESA, but it's not important for this question).
I plan to use the library ...
- 1,320
0
votes
0
answers
29
views
Insert custom documentation stub for classes with PyCharm
In my code, I have a bunch of subclasses of a few main classes each of them with some specificities. I am using PyCharm Community 2024.2.3.
I would like to be able to insert a documentation stub ...
- 313
0
votes
0
answers
61
views
Macro URL anchor substitution with MathJax in docstring
I have this docstring with a math directive that has a very long anchor pointing to the same page:
class MyClass:
r"""Intro text.
.. math::
\href{#the_very_long_anchor}...
- 12.7k
0
votes
1
answer
42
views
How to access params of example/template data table (cucumber)?
We use codeceptjs with cucumber for api tests. In the test steps we decided to use a docstring to hand over variables instead of a data tables.
Now the creation of a Scenario Outline (cucumber style) ...
- 1
0
votes
0
answers
60
views
Docstring shows twice in pycharm
I have a Python class with methods that include docstrings. When I hover over the method names in my IDE (I'm using PyCharm), the docstring content appears twice. Here's an example of one of my ...
- 82
0
votes
1
answer
62
views
In docstring, how to give multiple parameters the same description (using EpyText tags)?
For IDEs where hovering over a function call displays help (e.g. PyCharm), rather than create multiple lines with the same description for multiple parameters ... is there a way to simplify by tagging ...
- 357
0
votes
1
answer
26
views
No access to external python documentation of numpy library in pycharm
Pycharm is unable to access the documentation of numpy, and all other installed libraries. The runs correctly, but no inline documentation with a description of the function is provided when ...
- 3
-4
votes
1
answer
137
views
What is the proper way of including examples in Python docstrings? [duplicate]
How to include examples for function calls in Python docstrings? See @examples tag in R documentation. Or what is the proper way to include examples?
I'm looking for something like this:
def my_func(x)...
- 545
1
vote
0
answers
83
views
How to make clickable link compatible with IDEs and mkdocs?
My docstrings contain links. I want to make these links clickable in IDE, but I want to use the https://github.com/mkdocstrings/python to generate mkdocs api reference.
I want to use this package, ...
- 1,794
0
votes
0
answers
28
views
Access instance attribute docstring
According to PEP 258, it is possible to define an instance attribute docstring in the __init__ function, as in the given example:
g = 'module attribute (module-global variable)'
"""This ...
- 107
0
votes
1
answer
108
views
Extract Google style docstring into dataclass using Sphinx Napoleon
I am trying to programmatically ingest ("reflect") Google style docstrings. I am using sphinx.ext.napoleon, as seemingly not many tools do this. I am following this example with the below ...
- 2,331
0
votes
0
answers
49
views
Typescript docstring not generating proper documentation
I have below typescript docstring:
@param { Required<Pick<Model1, 'startTime' | 'endTime' | 'xyz'>> & Partial<Model1> } body specification
I run npm run documentation to ...
- 131
1
vote
0
answers
52
views
PyCharm highlighting docstring keywords
With the default reStructuredText format, PyCharm highlights words such as param, type, raise, and return, such as in the example below:
enter image description here
However, when I try another style ...
- 11
0
votes
1
answer
140
views
How to get docstrings of fields of a NamedTuple or dataclass?
I'm using a NamedTuple with comments as suggested for Python 3.6+:
from typing import NamedTuple
class Config(NamedTuple):
buy_fee: float
"""My field description...""&...
- 63.3k
1
vote
1
answer
103
views
How can I make VS Code also rename symbols in Python docstrings when refactoring?
I use VS Code in my Python projects, I currently use docstrings to document it. However, when I rename a symbol (F2), of a function parameter for example, it is not updated in the docstring. Do you ...
- 11
0
votes
0
answers
20
views
How to dynamically switch Python docstring based on flag in the code or sys environ
I've got a library which provides bunch of functions for the client. They can be accessed via:
from my_package import functions
functions.fun_a()
from my_package.functions import fun_b
fun_b()
...
- 1
0
votes
1
answer
142
views
Sphinx is throwing some indentation errors, and I cannot figure out how to fix them
These are the errors I am getting from Sphinx:
Unexpected indentation:
[{
"resource": "/c:/Users/User/Documents/GitHub/MIMIC/mimic/model_simulate/base_model.py",
"owner":...
0
votes
0
answers
27
views
Python Module Help DocStrings - Exclucing extra documentation
I have written a simple module (testmodule) which imports some other modules. When I import it and type:
help(testmodule)
I get all of the help from the imported modules as well.
Is there a way of ...
- 16.1k
0
votes
1
answer
124
views
Adjust yaml.Dumper to export dataclasses and their docstrings
I would like to export dataclass objects including their docstrings (as # commented description above) to yaml.
So far I've figured out that I need a custom dumper or adjust the current one.
from ...
- 3,288
1
vote
1
answer
259
views
sphinx docstrings and vscode
I have the following docstring:
def test(foo):
"""this is my function
.. code-block:: python
cool function
now I should be outside the codeblock.
But ...
- 409
0
votes
0
answers
41
views
Maintaining a Python function docstring via a separate Python script
My goal is to make a repeatable Python function doc string maintenance process that can be executed to update parameter options when they change as a function is developed. This would remove the need ...
- 11
0
votes
0
answers
65
views
Best practice for type annotation and docstring inheritance
I have a python class like this
class LinBlock(nn.Module):
def __init__(
self,
inp_features: int,
out_features: int,
activation: Callable[[], "...
- 89
0
votes
0
answers
71
views
How could I only include classes and functions docstring instead of module docstring when using Sphinx?
Let's say I have a python module like below:
test.py:
__doc__ = """This is the module docstring."""
class ClassA:
"""This is ClassA's docstring"&...
- 33
2
votes
0
answers
85
views
Is there a way to validate that methods and attributes listed in a Python class docstring exist within the class?
When writing docstrings for a class I wondered if there was a Python package that would parse the doc string of a class and validate that the class has the methods and attributes listed?
My motivation ...
- 23
0
votes
1
answer
65
views
PyCharm Google-docstring russian language parsing problems
I've a docstring in some function. This is a google-styled docstring. My PyCharm has enabled default syntax checking.
For some reasons I got a PEP hint, that the first letter in a sentence should be ...
- 179
0
votes
0
answers
25
views
is there a way/extension to add docstring-like annotations to parameter strings
I am currently using a request based module to call functions between containers in azure container apps. The default module looks like
send_request(method: str, endpoint: str, params: dict={}, ...
- 1
0
votes
1
answer
819
views
How do I disable D100 and or C0111 with ruff?
I use sphinx and at the top of my py files I have this:
#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
my-module
=========
Some notes about my module
"""
These ...
- 31.3k
0
votes
0
answers
236
views
Docstring doesn't show on hover in vscode jupyter notebook
When I import a function into a vscode notebook, instead of getting a docstring I just get this:
Here is the function:
def balance_binary_target(df, target="", ratio=None):
""&...
- 4,465
9
votes
1
answer
926
views
How do I document a type alias defined using `type` in Python?
Python 3.12 has the type statement. How do I document the type alias properly?
I tried:
type Number = int | float
"""Represents a scalar number that is either an integer or float"&...
- 823
0
votes
1
answer
156
views
Julia docstrings not rendered properly to VS Code (via LaTeX?)
I am new to the Julia language and trying out docstrings in a VSCode Jupyter notebook
"""
fibonacci(n)
Calculate the Fibonacci sequence up to the nth number.
# Arguments
- `n`: ...
- 22.4k
0
votes
1
answer
31
views
pdoc3 incorrectly rendered Args section
Recently migrated from an M1 to M2 mac. Previous successful invocation of pdoc was on M1 with Ventura 13.6, same python version. Is there a prerequisite I'm missing, or maybe need to downgrade a ...
- 1,157
3
votes
1
answer
99
views
What is the reason that child class does not inherit `__doc__` property/method?
I am a bit confused about the difference in behavior between __doc__ and other methods:
# python 3.10.13
class Parent:
def __init__(self, doc):
self._doc = doc
def __doc__(self):
...
- 95
3
votes
1
answer
344
views
How to access docstrings of enum-values in Python?
For a code documentation tool, I want to analyze a Python Enum class and print its details. Docstrings of the individual enum values shall be printed, as well.
However, as Enum values appear as their ...
- 71
0
votes
1
answer
136
views
Is there something like "f-docstring"?
I want to mention default values for function arguments in the function descriptions (docstrings).
What I don't want to do is to manually edit the docstrings, whenever I try out new default values
So, ...
- 19
0
votes
1
answer
258
views
Reference Section to Python Google Docstring
Does anyone know of a good way to include references in a python docstring that follows the google formatting? I'm writing a series of fluid property generators. I wanted a way to easily document a ...
- 23
0
votes
0
answers
338
views
How to handle *args in python docstring?
I have a some functions in my code that are specified like this:
def myfunction(self, *args, **kwargs):
I need these functions to be a bit flexible on how they are called such that they will still run ...
1
vote
2
answers
399
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 ...
- 21
3
votes
1
answer
725
views
Replacing a SimpleString inside a libcst function definition? (dataclasses.FrozenInstanceError: cannot assign to field 'body')
Context
While trying to use the libcst module, I am experiencing some difficulties updating a documentation of a function.
MWE
To reproduce the error, the following minimal working example (MWE) is ...
- 2,738
1
vote
1
answer
850
views
python: how to use type annotations and docstring formats together
Now that we have type annotations in Python, I'm wondering how to document code with type annotations AND docstring formats.
Specifically, it seems redundant to specify the argument types as an ...
- 10.7k
1
vote
0
answers
59
views
Python Docstring: how to document a function that returned an other function?
I do Flask app. How to document a function that returned an other function?
@mod.route('/report')
def function():
""""
Function call 'function_2' for display report
:...
- 91
1
vote
0
answers
69
views
Add a docstring to an entire Jupyter notebook
In my office, we frequently create Jupyter notebooks with helper functions for a project, then use %run magic to import those functions into other working notebooks as we need them. We always add a ...
- 125
1
vote
0
answers
709
views
How can I get hover over to display inherited code for python classes in VSCode?
I have written a base repository and cookiecutter that defines abstract django models and other helpers for celery workflow systems.
The aim was to standardise the workflows we create and keep them ...
- 21
1
vote
0
answers
1k
views
In VSCode, how to get on-hover documentation shown for class properties documented in the class docstring?
The code base I'm working has a convention on to how to document class attributes.
Here's how it looks:
@dataclass
class SessionMetadata:
"""Metadata of a Session
Attributes:
...
- 396
3
votes
1
answer
975
views
How can I get hover info in VS Code for Google/Sphinx-style Python class attributes documentation? (like "#: text")
I'm trying to document instance variables in my Python classes so they show up in VS Code when I hover over them. I've found that this works:
class TsCity:
def __init__(self) -> None:
self....
- 606