Dev Docs: Add "Edit|History|Report Issue|Discuss" Links To Subheads

[harding]

Previews:

• http://dg2.dtrt.org/en/developer-guide
• http://dg2.dtrt.org/en/developer-reference
• http://dg2.dtrt.org/en/developer-examples

This pull adds contextual links below most subheadings. They look like this:

This helps solve a few minor problems with the current Javascript-based left-side links:

1. Javascript is not required for these new links to work fully. This is a really minor issue since JS is still required to get rid of the BETA warning pop-up.
2. These new links are much more visible than the old links on long sections. This was discussed on issue #647
3. When sections from two different files are both displayed at the same time, clicking the old Edit or Issue links may operate on the wrong file.

Number 3 was my main motivation. On a WIP branch, I've split each of the RPC subsections into a different file, greatly increasing the chance a prospective editor/bug reporter will get the wrong context.

In addition, I think having the links displayed under every section will gently remind users over and over that they too can contribute, or point them in the direction of interactive help if they're confused.

I'm sure this pull can be improved upon, so please let me know what ya'll think.

[saivann]

@harding Great, I like it! My only issue is with readability, I've sent you a pull request to try improving that.

Depending on if we keep the "Edit on GitHub" link on the table of content, we should either drop the "sourcefile" information in en/developer-guide|reference|examples, or move this information in each _includes/* files in such a way that we don't set this information twice in two different files IMO.

[harding]

@saivann thanks! Re: your suggestions,

1. Pull request merged. Thanks! That is definitely a nice improvement.
2. I agree. In commit 53d4a6e, I removed the manual sourcefile divs and added that info to the automatically-generated subhead-links divs. This seems to work, but could you please review that commit? I removed the CSS for the sourcefile class but I wasn't sure whether any of that (particularly the absolute position) was important.

I updated the preview with both yours and my commits. Thanks again!

In the absence of critical feedback, I'll merge this pull in about 48 hours (13:00 UTC Tuesday).

[saivann]

@harding For the record, I haven't had time to test the links or review the new Makefile tests yet, but otherwise this all LGTM. Thanks!

[harding]

@saivann thanks for all your help! The makefile tests in combination with the new liquid-die.rb plugin should ensure no completely broken links are created. It is possible that a link might point to the wrong file if {%filename="parent.md"%} is set in a parent file that includes a child file with a different name, and that child file doesn't set its own filename. For that reason I've made sure the top-level files (en/developer-*) that do all the including don't set their own filenames.

I've scrolled through the entirety of all three pages looking for formatting snafus and checked a bunch of the links without finding any problems. Of course, more testing is always better.