Repository: readthedocs/readthedocs.org

Issue:
Broken edit links
Two issues which may or may not be related:
- Module sources: the "Edit on github" links for pages like http://www.tornadoweb.org/en/stable/_modules/tornado/stack_context.html are broken; they point to a non-existent .rst file. Is it possible to suppress the edit link for these pages (or ideally point it to the real source)? (migrated from https://github.com/snide/sphinx_rtd_theme/issues/237)
- Non-latest branches: on a page like http://www.tornadoweb.org/en/stable/, the "edit on github" link in the upper right is broken because it points to https://github.com/tornadoweb/tornado/blob/origin/stable/docs/index.rst (the 'origin' directory needs to be removed from the path). On the lower left, clicking "v: stable" for the menu and then "Edit" works (linking to https://github.com/tornadoweb/tornado/edit/stable/docs/index.rst).

The "latest" branch works fine (linking to "master"); this is only a problem for pages based on other branches (migrated from https://github.com/snide/sphinx_rtd_theme/issues/236)



Discussion:
Thanks for the report! Indeed these are two distinct issues. The first will be addressed with #1643.

I also had a look at the second, but it's a little tricky. The reason is that `stable` usually is a special version name on our end. We alias the branch or tag of a project that is a valid version number (like v1.3.4) and the highest version number of all tags/branches as being the `stable` version. So that's why this name gets an extra treatment.

The Tornado project seems to suffer from this a little as you have a branch called `stable`. Now the reason why the link in the footer-popup (clicking `v: stable`) works is that this part of the page does not check for the special `stable` name (so actually it's broken for all projects that are not having a `stable` branch in the project) and the link at the top of the page "Edit on GitHub" is broken for your case as it checks for the special name.

I will try to come up with a fix but currently I think for really making the "stable" special casing work, we might need to refactor how we store the branch/commit identifier information. I'll keep you posted.

Ah, I didn't realize that about `stable`. I'm using the `stable` branch to do essentially the same thing by hand, so maybe I can just get rid of my branch. How would I replace my `stable` branch with an alias for `branch4.2` or tag `v4.2.1`?

We are trying to figure out the stable branch ourself by parsing all available branch and tag names. The highest valid version number that is compliant to [PEP-440](https://www.python.org/dev/peps/pep-0440/) we be set as the stable branch.

So if I just delete my `stable` branch from github, readthedocs will see that it's gone and replace it with one of my branches or tags?

The second point of your issue will be addressed with #1650 

@bdarnell Should work this way, yes. Maybe you need to push one commit (should be irrelevant which branch) since I don't know if the deletion of a branch triggers a post commit hook.

The second point (bad links from the top right "Edit on GitHub" page) will be fixed with the next deploy as we have merged #1650 

So is it fixed?

The issue with the "Edit on Github" for auto-generated pages is still present. I just tried it in my local instance of RTD and I can see the link for auto-generated pages. Also, the last issue linked here from another repo is from November 2016.

Regarding the second one and the branches, I'm not really sure to understand it or how to make a good test.

Resolving patch:
diff --git a/readthedocs/vcs_support/backends/git.py b/readthedocs/vcs_support/backends/git.py
--- a/readthedocs/vcs_support/backends/git.py
+++ b/readthedocs/vcs_support/backends/git.py
@@ -92,7 +92,15 @@ def clone(self):
 
     @property
     def tags(self):
-        retcode, stdout, _ = self.run('git', 'show-ref', '--tags')
+        # Hash for non-annotated tag is its commit hash, but for annotated tag it
+        # points to tag itself, so we need to dereference annotated tags.
+        # The output format is the same as `git show-ref --tags`, but with hashes
+        # of annotated tags pointing to tagged commits.
+        retcode, stdout, _ = self.run(
+            'git', 'for-each-ref',
+            '--format="%(if)%(*objectname)%(then)%(*objectname)'
+            '%(else)%(objectname)%(end) %(refname)"',
+            'refs/tags')
         # error (or no tags found)
         if retcode != 0:
             return []
@@ -100,7 +108,7 @@ def tags(self):
 
     def parse_tags(self, data):
         """
-        Parses output of show-ref --tags, eg:
+        Parses output of `git show-ref --tags`, eg:
 
             3b32886c8d3cb815df3793b3937b2e91d0fb00f1 refs/tags/2.0.0
             bd533a768ff661991a689d3758fcfe72f455435d refs/tags/2.0.1


Test patch: