read the docs - Sphinx RTD Theme and New Lines -

i have written library in python 3 , in process of documenting class, methods, constants, etc.

i having subtle formatting issue constants lists or dicts. organization has taken position lists , dicts should written in following format readability...

my_list = [     'one',     'two',     'three', ]  my_dict = {     'one': 1,     'two': 2,     'three': 3, } 

in class have constants lists, example:

std_list = [     'item1',     'item2',     'item3', ] 

and i've copied list , other class constants class docstring , written paragraph explaining each's significance. if want html documents have nice formatting using vertical bar ("|") force new lines.

here restructuredtext:

|     **std_list = [** |         **'item1',** |         **'item2',** |         **'item3',** |     **]**          list important. please not modify unless know         doing. best not touch ever!          .. warning:: don't touch :py:const:`std_list` unless know \         doing. 

but following happens:

the problem here is, said subtle, i'm sort of perfectionist. when normal constant documented description indented. when vertical bars used disrupts indentation. (compare image below)

i have found if remove blank line between constant declaration , description makes description continue on last line of list. if add vertical bar @ first line of description corrects problem entirely causes issues next constant down below not adding blank line between them.

does know how achieve consistency rest , sphinx in case this? think being able force newline between constants in docstring adequate work-around.

i got through typing question , had try worked. hope solution helps other people. answer messy works. if has better solution, please post it!

apparently problem blank line between declaration of constant , explanation use. remove blank line.

but causing first line of description run on same line first line of description. solve this, add vertical bar @ first line of description.

but theeeeeennnnn.... causing constant , 1 after have virtually no blank space between them, annoying too. had force new line adding yet vertical bar on line of own on line after description. here's final solution:

|     **std_list = [** |         **'item1',** |         **'item2',** |         **'item3',** |     **]** |         list important. please not modify unless know           doing. best not touch ever!            .. warning:: don't touch :py:const:`std_list` unless know \           doing. |      **next_const = 'stackoverflow.com amazing!'**         shoutout stackoverflow.com admins , users. normal constant          string , doesn't need vertical bar trickery sphinx format          nicely. 

the following nicely formatted output , looking for:

exception: when description ends admonition there no need add vertical bar after admonition. instead, move vertical bar line after text description , include blank line before admonition so:

|     **std_list = [** |         **'item1',** |         **'item2',** |         **'item3',** |     **]** |         list important. please not modify unless know           doing. best not touch ever! |            .. warning:: don't touch :py:const:`std_list` unless know \           doing.      **next_const = 'stackoverflow.com amazing!'**         shoutout stackoverflow.com admins , users. normal constant          string , doesn't need vertical bar trickery sphinx format          nicely.