Best practice to document a complex nested dictionary parameter in a Python docstring?

user_6308448 0
Viewed 563

for a project I am working on, I have written a function that creates multiple animations with matplotlib. The problem is, the function accepts a fairly complex and (if I'm being completely honest) unintuitive nested dictionary as its main parameter. Currently, the dictionary has the following format:

dictionary = {`int` : {keyword_argument : {sub_keyword_argument : boolean,
                                           sub_keyword_argument : boolean},
                       keyword_argument : function object,
                       keyword_argument : tuple containing arguments for the above function object}

So definitely not the easiest parameter to work with. As such, I feel the easiest way to document this in a function docstring is to use a table but as far as I can tell, there is no in built way to create a table inside a Python docstring. I'm just wondering what would be the best way to document this parameter in a docstring that explains how it all works.

I've also considered just separating the parameter into three separate dictionary arguments where the keys of each dictionary argument is int. However, the way the function works, each dictionary would have to have the same keys anyways so I though I might as well put them all into one big dictionary. To be honest, I'm actually not sure which would be the best practice either.

docstring python
1 Answers

Python docstrings can have any format you like.

However, the standard tools for Python documentations support reStructuredText, which support multiple syntaxes for tables, e.g.:

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

However, if this is as unfriendly as you think, you may want to consider splitting this single parameter into multiple simpler parameters.

user_52183540
Related