Как лучше документировать сложный вложенный параметр словаря в строке документации Python?

Question

для проекта, над которым я работаю, я написал функцию, которая создает несколько анимаций с помощью matplotlib. Проблема в том, что функция принимает довольно сложный и (если я полностью честен) неинтуитивный вложенный словарь в качестве основного параметра. В настоящее время словарь имеет следующий формат:

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}

Так что определенно не самый простой параметр для работы. Поэтому я считаю, что самый простой способ документировать это в строке документации - это использовать таблицу, но, насколько я могу судить, встроенного способа создания таблицы внутри строки документации Python не существует. Мне просто интересно, как лучше всего документировать этот параметр в строке документации, которая объясняет, как все это работает.

Я также рассмотрел просто разделение параметра на три отдельных словарных аргумента, где ключами каждого словарного аргумента являются int. Однако, как работает функция, каждый словарь должен был бы иметь одинаковые ключи в любом случае, поэтому я мог бы с тем же успехом поместить их все в один большой словарь. Честно говоря, я на самом деле не уверен, что будет лучшей практикой.

Answer 1

Строки документов Python могут иметь любой формат, который вам нравится.

Однако стандартные инструменты для документации Python поддерживают reStructuredText , которые поддерживают несколько синтаксисов для таблиц, например:

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

Однако, если это так недружелюбно, как вы думаете, вы можете рассмотреть возможность разделения этого единственного параметра на несколько более простых параметров.