[Python] How should I document Python constants so they are reflected in the comments of the...

I have a file called constants.py where I store all my constants, such as paths PATH_DATASETS = "data/datasets/" or values WIDTH = 416.

They are use multiples times in the code, sometimes as default values for functions such as

def main_train(..., width: int = constants.WIDTH,...):


In the documentation I have:

Args:
width (int):
Width of the network from which the images will be processed. Must be a multiple of 32. The default is constants.WIDTH.


Now, if I write the main_train function, when I hover it to see help I see constants.WIDTH and not 416. Also, when using Sphinx, the docs show:

width (int) – Width of the network from which the images will be processed. Must be a multiple of 32. The default is constants.WIDTH.


But in Sphinx, if I look how the function is declared I can see:

main.main_train(path_home: PurePath, path_dataset: PurePath, template: List[PurePath], width: int = 416,


Should I drop The default is constants.WIDTH. from my function's comments as Sphinx already reflects it? I would have no mode to see the default option hovering in VSCode. Or should I substitute the constants' name for its value? That way it would be painful to update my documentation each time I want to change a constant.

I have found a question similar, but in C#/xml, so I can't use its solution.

Many thanks.

Continue reading...