Make it easy to open a documentation bug from the docs themselves

Maybe we can add paragraph level "report bug" links that link to the issues/new page?

Can we also link to the source of the document in the github edit UI so people can fix and send a PR?

@silvolu

@silvolu I seem to remember you doing something like this based on readthedocs (example):

Did this happen in gcloud-node? I know it was brought up but I'm not sure if it ever came to be.

Doesn't appear that we've added this on gcloud-node yet either (
http://googlecloudplatform.github.io/gcloud-node/#/docs/v0.12.0/datastore/transaction
)

We have an "Edit on GitHub" link on the two pages that are generated from MD: https://googlecloudplatform.github.io/gcloud-node/#/faq and https://googlecloudplatform.github.io/gcloud-node/#/troubleshooting

For reference, my comment on the version fix (for #472) points out where to put something like this.

Made a comment on another bug, but putting it here for reference:

I think it's important that if I scroll far down into a section of the docs, and see a problem with a specific thing (ie, say the note on http://googlecloudplatform.github.io/gcloud-python/storage-blobs.html#gcloud.storage.blob.Blob.upload_from_file), I shouldn't have to scroll all the way back up -- I'd want to click "edit" right there and be taken to the right place...

Any chance we can do that? Maybe have the issue body pre-filled with the method that has the issue?

I'll also port over my comment:

We could put the "file docs bug" in our Big Blue Bar(TM) which stays fixed at the top of each page.

As for pre-filling issue body, I'd have to learn a bit more about what GitHub allows.

UPDATE: That was easy https://github.com/GoogleCloudPlatform/gcloud-python/issues/new?title=foo&body=bar

@jgeewax

@jgeewax WDYT of:

This also drops "Python" from #538, though I noticed Node.js is the title in node land.

This becomes an issue when the nav gets collapsed when page width goes down i.e. for mobile (responsive web dev).

Would you like to see "Report an Issue" folded into the nav hamburger (3 stacked white bars on RHS) or somewhere else?

If we can't pre-populate the bug text with anything (ie, "method was ....") then this is great -- and we just need some responsive tweaks.

Pre-populating will be possible. E.g.:

https://github.com/GoogleCloudPlatform/gcloud-python/issues/new?body=Commit%3A%2008fae45%0APage%3A%20http%3A%2F%2Fgooglecloudplatform.github.io%2Fgcloud-python%2Flatest%2Fdatastore-entities.html

Need to get #624 and #625 in before though so we don't have conflicting things flying by

UPDATE:

Having the source is not always possible since the docs are generated from RST. We might be able to map it though?
We'd need to embed the commit hash in ever page as a data attribute, but that's easy enough to do

An example for getting the source path in our template:

      {%- if show_source and has_source and sourcename %}
      |
      <a href="{{ pathto('_sources/' + sourcename, true)|e }}"
          rel="nofollow">{{ _('Page source') }}</a></li>
      {%- endif %}

The Sphinx docs also describe what show_source is (but I find their docs a bit unparseable).