DOC: Refactor code in the fishbone diagram example

[saranti]

PR summary

• Simplify the code in the cause and draw_body functions.
• Remove the draw_spine code from draw_body and turn into its own function.
  • Fixed issue where the spine was being rendered multiple times due to being inside a loop.
• Improve docstrings and comments.
• Other minor changes.

[timhoffm]

Suggested change

	tail_pos = [[-2.8 - length, 0.8], [-2.8 - length, -0.8], [-2.0 - length, -0.01]]
	tail_pos = [[-2.8 - length, 0.8], [-2.8 - length, -0.8], [-2.0 - length, -0.01]]
	draw_spine(spine_length, head_pos, tail_pos)

Let's move drawing the spine up here, this is where all relevant input for the function is calculated. Also, it's the order , you would draw such a diagram by hand: first the spine, and then the problem categories.

[timhoffm]

It may even be a good idea to pull all the positioning details in to the function, so that you do

draw_spine(-2 - length, 2 + length)

which gives the length of the line.

Note that the left of spine_length is -0.1 compared to that, which I assume is so that the line reaches into the tail triangle. Otherwise the transition may not look smooth. But that should be an implementation detail, i.e. (or so - untested)

def draw_spine(xmin, xmax):
    ...
    # draw main spine
    ax.plot([xmin-0.1, xmax], [0, 0], color='tab:blue', linewidth=2)
    # draw fish head
    ax.text(xmax + 0.1, - 0.05, 'PROBLEM', fontsize=10,
            weight='bold', color='white')
    semicircle = Wedge((xmax, 0), 1, 270, 90, fc='tab:blue')
    ax.add_patch(semicircle)
    # draw fishtail
    tail_pos = [[xmin - 0.8, 0.8], [xmin - 0.8, -0.8], [xmin, -0.01]]
    triangle = Polygon(tail, fc='tab:blue')
    ax.add_patch(triangle)

[timhoffm]

Suggested change

draw_spine(spine_length, head_pos, tail_pos)