revisit outstanding items in docs build

[jGaboardi]

• revisit outstanding items in docs build
• following for this here among other stuff
• xref
  • pruning down warnings/errors in make html #394
  • fix docs build directory mismatch #393

[sjsrey]

I'm not sure if this is part of the "other stuff" but the images are broken on the docs:

[jGaboardi]

I'm not sure if this is part of the "other stuff" but the images are broken on the docs:

The docs action has not been run since before the image stuff was updated. While the docs are not completely perfect with those updates from #394, there are some improvements, especially the image fixes. Shall we go ahead trigger the doc rebuild action?

[martinfleis]

we should trigger docs refactoring here...