Remove in-product /help, redirect to docs.sourcegraph.com
Created by: sqs
- Revert e5e1c2393e4c9665f14da3eea3ad667a30ebdb05
- Remove dependency on github.com/sourcegraph/docsite/markdown, revert to using previously used Markdown packages
- Fix #2369
- Help with #1361
- Remove in-product rendered /help pages, redirect to equivalent https://docs.sourcegraph.com page for the current product version instead
- Close #2337
- Fix #1720
- Fix #1912
- Close #1885
- Remove dependency on github.com/sourcegraph/docsite
Notes
No docs for untagged releases
To redirect /help/PATH
in-product to https://docs.sourcegraph.com/@v1.2.3/PATH, a Sourcegraph instance needs to know the v1.2.3
(Git revspec for its current version). This is easy for true releases and release candidates, since for them "v" + version.Version()
is a valid Git revspec. We special-case dev builds (version.Version() == "dev"
) and Sourcegraph.com.
However, if you are running Sourcegraph with a version string that is NOT a valid Git tag (revspec) on the remote, there is no way for the instance to perform the proper redirect. It's also not really feasible for the instance to detect this case and report it (the user would just be redirected to a 404ing https://docs.sourcegraph.com/@some-invalid-version/PATH URL).
I think this is acceptable because I am unaware of why such an untagged build would exist where the doc links would need to work. If we need to give a customer a hotpatch, we should just release a patch version normally. (In extreme, unforeseeable circumstances where we would release an untagged build, having doc links not working is probably low down on the list of concerns because something else must be extremely urgent.)
TODO
This is ready to review.
-
Ensure behavior is correct on Sourcegraph.com (should link to version-less docs.sourcegraph.com URL). -
Investigate whether the version.Version()
string always corresponds to a valid Git tag in all the cases that matter (releases, release candidates, hotfix versions for customers, etc.?). (See "No docs for untagged releases above" for the answer to this.) -
Make our React app handle /help/PATH
redirects (currently these are only handled by Go, so react-router<Link>
s to/help/PATH
don't redirect). (This has a slight bug with the back button in dev mode only that will be addressed by adding docsite on http://localhost:5080 to Procfile, mentioned below as being planned for a future PR.) -
Test that search results are syntax-highlighted correctly. -
Test that Markdown is rendered correctly for .md
files, code discussions, and saved search emails (or confirm that we have automated tests for these).
Followup work in a future (this week) PR
-
Move https://github.com/sourcegraph/docs.sourcegraph.com into this repository. -
Add docsite
running on http://localhost:5080 toProcfile
so devs can preview local doc changes again. -
Add lint step to ensure that /help/PATH
links (in<a>
and react-router<Link>
and in text/bare URLs) refer to doc pages that actually exist in the current commit. -
Update all absolute links to https://docs.sourcegraph.com/PATH to /help/PATH
to ensure the link goes to the docs for the current product version.