Refactor documentation links to source on GitHub

[kitchoi]

The documentation has URL links to sources on GitHub. Some of them can be replaced by cross references to the API documentation. Some of them cannot.

When we need to move files across (e.g. for solving #320, see #359), we would have to update these links laboriously. This PR refactors the links so that "https://github.com/enthought/envisage/tree/master/..." is only defined once, in conf.py. And when we do move the example files, only the link in conf.py requires changes.

There are some drive-by to replace GitHub links with API documentation references, as well as removing some dead links.

[aaronayres35]

LGTM!
I did have one question though: why not include |Hello World|, or |Plugin|, etc. in the conf.py file. It seems that they only needed to be updated in a single file, so if we were changing them there is only 1 place to update them anyway, which makes sense. But, that might not be obvious initially though, and someone might think that when things get moved they only need to update the links in confy.py.

Not a suggested change, just something to consider. It certainly might be overkill to try to keep track of all reference links in conf.py. Some of them like |Plugin| though could potentially be referenced in more places as documentation is updated.

Also I built the docs and things look good. I did not try every single link, but did a random sample and it all seems to work as expected.

[aaronayres35]

Im guessing the reason we have two things linking to MOTD/acme/motd/motd_plugin.py is because they existed both ways in the docs currently? That seems fine to me, but maybe we would want to consolidate so any doc trying to link to this page says either |acme.motd| or |MOTDPlugin|?

[kitchoi]

Yes they both reference to the same file, but they are different appearance so by keeping both, we keep the sentences unchanged.
|acme.motd| will appear as "acme.motd" that links to the motd_plugin.py file. MOTDPlugin will appear as "MOTDPlugin" that links to the same file.

[mdickinson]

You could always change the link text in the place that's referring to the link.

[mdickinson]

Ah, sorry; ignore me. I was missing context.

[aaronayres35]

LGTM!
I did have one question though: why not include |Hello World|, or |Plugin|, etc. in the conf.py file. It seems that they only needed to be updated in a single file, so if we were changing them there is only 1 place to update them anyway, which makes sense. But, that might not be obvious initially though, and someone might think that when things get moved they only need to update the links in confy.py.

Not a suggested change, just something to consider. It certainly might be overkill to try to keep track of all reference links in conf.py. Some of them like |Plugin| though could potentially be referenced in more places as documentation is updated.

Also I built the docs and things look good. I did not try every single link, but did a random sample and it all seems to work as expected.

I guess moving files would really only require changes to this:

'github-demo': (
        'https://github.com/enthought/envisage/tree/master/examples/%s',   # noqa: E501
        '')

as others all link to api docs...
So feel free to disregard my comment (although I do still find it a little confusing why |ExtensionPoint| is included but |Plugin| is not, etc.

[kitchoi]

I did have one question though: why not include |Hello World|, or |Plugin|, etc. in the conf.py file. It seems that they only needed to be updated in a single file, so if we were changing them there is only 1 place to update them anyway, which makes sense. But, that might not be obvious initially though, and someone might think that when things get moved they only need to update the links in confy.py.

Agreed it would be clearer if the substitutions are maintained in one place. I moved those across to conf.py too.

[aaronayres35]

Still LGTM! Thank you!