Consider shuffling run() docs around for visibility purposes

[bitprophet]

Background

• As of released 0.12.x docs, to get to the actual docs for run() (any version of it) one has to drill down to the runners module -> Runner class -> run method - and if coming from __init__.run(), one has to get there via Context.run.
  • This is 100% accurate re: where the code lives / how __init__.run() works, but it's also a pain for users, especially new ones. Conceptual complexity etc etc.
• Recently I tweaked things a bit so the __init__.run() docs directly link to Runner.run, instead of making you go via Context.run. Better, but still not great.
• I'm considering moving the bulk of Runner.run's docstring to either __init__.run() or a distinct conceptual document:
  • In terms of keeping it as "API documentation", having it in some func/method docstring is "more correct".
    • But I don't want to overly encourage newbies to think __init__.run() is something they should be using primarily/by default, instead of creating/obtaining Contexts and using their run method.
  • Moving it into a concept doc feels better for visibility purposes - a clearinghouse "this is about command running, period, which is exposed in a handful of places depending on what you're doing" that can be linked to from anywhere, and links outwards to the "real" API endpoints.
    • However, it always feels kinda gross to have 'pointers' in API docs, especially re: moving the docs outside of the implementing module.
    • Counterpoint: that's a long-running doc issue with no clear right answer; code changes always require modifying 'external' files like docs, changelogs & tests regardless; and visibility generally trumps 'correctness', especially when doing so isn't actually sacrificing DRY.
  • Another argument for moving it to a concepts doc is that the usual big benefit of Sphinx apidoc - having a signature and corresponding :param elements - is already invalid with run() because it's implemented via **kwargs.

To do

• Move the run() docstring to a new concepts doc.
• Have that doc clearly link to __init__.run(), Context.run, and Runner.run.
• Have the docstrings for those in turn link back to the new doc.
• Update the changelog so references to run go to this doc instead of whichever docstring they went to before.
  • When the changelog entry is very specifically about a given 'location', it can stay as-is.
  • Bonus: there's probably some inconsistency in those links anyways (?) so this would fix that too.