github links, custom commit/tags support.

[bd82]

Example:

documentation build -f html -o docs  --github v0.12.39

A link to the sources would now look like: (using a random repo as an example)
https://github.com/gatsbyjs/gatsby/blob/v0.12.39/lib/isomorphic/create-routes.js#L7
instead of something like:
https://github.com/gatsbyjs/gatsby/blob/cefdefc8f330957f8a340e0f5cf026dc2b9ec14f/lib/isomorphic/create-routes.js#L7

Rational

I don't much care about html docs for my master branch.
Instead I would prefer that the html docs posted on my gh-pages to link
to the latest released tag's docs.

I don't expect documentation.js to support my specific work flow.
However by supporting a generic argument for the tag/commit id such a flow and
possibly other custom ones could be enabled.

[bd82]

Actually when I think about it linking to the latest commit covers my specific flow already.
although it would be slightly prettier to have tag numbers in the links instead of commit hashes.

[tmcw]

I think this seems like a good thing, some points of ambiguity / design to consider:

• I wouldn't want to make this user-configurable, because the idea of the git referencing is that the referencing is accurate up to the line. If someone is able to choose an arbitrary tag, they can choose wrong, choose a tag that doesn't exist or that doesn't match the local tree.
• Tags are slightly less reliable than commit shas because they can be replaced, you can tag -d and delete and replace them, whereas commits are almost impossible to mess up.
• Here's the code that calculates url_prefix: I think if we were to test the current sha and see if it matches a tag, we could automatically prefer the (first found) tag that matches.

[bd82]

I wouldn't want to make this user-configurable

A default value is good, but the ability to override it (explicitly) enables flexibility for use
cases not originally considered. Once you explicitly override a value you take responsibility 😄 .

It seems that the combination of npm deployment triggered by pushing a tag is very common.
https://github.com/search?utf8=%E2%9C%93&q=filename%3A.travis.yml++provider%3A+npm+tags%3A+true&type=Code
(Almost 12k results just for travis.yml files)

So I assume users know what they want and take responsibility when they trigger their release jobs which create the tags...

I think if we were to test the current sha and see if it matches a tag, we could automatically prefer the (first found) tag that matches.

I'm not familiar with the git's data structures, hopefully this tag information is easily accessible.
Note that doing this automatically will force the creation of the tag prior to running the documentation generation. Its not a big deal to modify, but my own release scripts for
an OSS I develop create and push the tag as the last step of the script.

[bd82]

If someone is able to choose an arbitrary tag, they can choose wrong, choose a tag that doesn't exist or that doesn't match the local tree.

Is the correct situation always correct?
It uses the latest SHA id as I understand, I have little understanding of git data structures so
forgive me if the following questions seem odd 😄

• Does this SHA id remain valid after a pull request has been merged?
• What if the pull request contains 5 commits which are squashed before merging (via github UI)
  Does the squashed commit retains the SHA of the last commit?
  • What if the doc generation was done in the 3/5 commits, than what will happen to its links?
    point to some commit that was never merged to master?
• Does the current flow work for editing both source files and generating docs in the same commit?

[tmcw]

Does this SHA id remain valid after a pull request has been merged?

Yep, for instance: see #767 which was composed of 6adabd5 and 9b1c41b . Those were squashed into 11d9045 when they were merged into master, but are still valid.

Does the squashed commit retains the SHA of the last commit?

No, the squashed commit has a new ID, which is the intent, since it's a separate: the last commit in the PR contains different changes than the squashed commit. Commit SHAs reflect both the working tree and the commit metadata (author, title, etc) itself.

[bd82]

Thanks for the explanation.

[tmcw]

Closing this issue with the status that

• A PR implementing this change would be definitely considered and likely accepted
• But this isn't critical and there are some tricky details that make the proposed implementation possibly dangerous: essentially, they'd make documentation.js less reliable by removing the guarantee it currently has that links link to the right thing. A PR would have to handle that uncertainty, and thus is larger than something that I want to slot in for implementation time.

Thanks for the suggestion, and if you'd like to implement it, I'd happily considering accepting a contribution to core!

[bd82]

Thanks for the update.

I don't think I've got the time to invest in this right now (other higher priority OSS work...).
And the original reason that I evaluated documentation.js has probably became moot
as I am thinking of switching that project to TypeScript and fix all(most) my woes in one fell swoop. 😄

And thanks for creating Documentation.js 👍