pythondocstring

How to format docstrings so they are displayed correctly in an IDE help window


Parts of my documentation aren't displayed correctly when opened in the IDE'S (Spyder6) help window.

I've googled the issue and looked for an answer on stackoverflow, but to no avail.

Below the "drawing" that get's scrambled as an example.

"""
These functions assume you're using objects to represent tiles, units, items, 
etc. on a map that is made up of hexagonally shaped tiles, with a flat side as top.
It furthermore assumes you're using a 3-dimensional cartesian coordinate system,
that assigns the coordinates along axis parallel to the orientation of the sides
of each hexagon. Like in the example given below. When using Pygame-CE it is 
recommended to use square images and draw a hexagon on them. An example of a 
64x64 tile is provided, it's intended to be used with the transparency colorcode 
set to (255, 0, 255). Currently the package does not support drawing hexagons.

      +s \        / -r
          \  _   /                   A: ( q=0, r=0, s=0 )
         _ / B \ _                   B: ( q=0, r=-1, s=1 )
       / G \ _ / C \                 C: ( q=1, r=-1, s=0 )
 -q __ \ _ / A \ _ / __ +q           D: ( q=1, r=0, s=-1 )
       / F \ _ / D \                 E: ( q=0, r=1, s=-1 )
       \ _ / E \ _ /                 F: ( q=-1, r=1, s=0 )
           \ _ /                     G: ( q=-1, r=0, s=1 )
         /      \
     +r /        \ -s
"""

In the red circle in the picture below, you can see how the result is being displayed in the IDE's help window.

The scrambled text is in the red circle.

If there is a way to format text so it stays together as intended please let me know. The expected output is the input.


Solution

  • Use a code block as if you were writing documentation using Sphinx:

    """
    Usage
    -----
    
    These functions assume you're using objects to represent tiles, units, items, etc on a
    map that is made up of hexagonal shaped tiles, with a flat side as top. It furthermore
    assumes you're using a 3-dimensional cartesian coordinate system, that assigns the
    coordinates along axis parallel to the orientation of the sides of each hexagon. Like in
    the example given below. When using Pygame-CE it is recommended to use square images and
    draw a hexagon on them. An example of a 64x64 tile is provided, it's intended to be used
    with the transparency colorcode set to (255, 0, 255). Currently the package does not
    support drawing hexagons.
    
    .. code-block::
    
              +s \     / -r
                  \ _ /                   A: ( q=0, r=0, s=0 )
                _ / B \ _                 B: ( q=0, r=-1, s=1 )
              / G \ _ / C \               C: ( q=1, r=-1, s=0 )
        -q __ \ _ / A \ _ / __ +q         D: ( q=1, r=0, s=-1 )
              / F \ _ / D \               E: ( q=0, r=1, s=-1 )
              \ _ / E \ _ /               F: ( q=-1, r=1, s=0 )
                  \ _ /                   G: ( q=-1, r=0, s=1 )
                  /   \
              +r /     \ -s
    
    Contains all hextile logic, specified as logic handling the relationship between
    cartesian coordinates and cube coordinates, for the purpose of defining the relative
    position of hexagon tiles on the screen. In addition it provides calculations in regards
    to hextile map related formulas and algorithms.
    """