Skip to content

Remove in-product /help, redirect to docs.sourcegraph.com

Administrator requested to merge remove-inline-help-docsite into master

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

Merge request reports

Loading