artin/sourcegraph
1
0
Fork 0
mirror of https://github.com/sourcegraph/sourcegraph.git synced 2026-02-06 20:11:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

check for broken links, etc., in documentation in CI (#1591)

Browse Source 
* go get github.com/sourcegraph/docsite@master

* check for broken links, etc., in documentation in CI

Running `docsite check` at the top level also runs the checker.
This commit is contained in:
Quinn Slack 2018-12-31 23:42:48 -06:00 committed by GitHub
parent 6d8f2ac9e0
commit ededdfc5ae
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 99 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
cmd/frontend/docsite/graphql.go
View File

@ -2,7 +2,10 @@ package docsite
import (
"bytes"
"context"
"errors"
"html/template"
"net/http"
"net/url"
"os"
@ -12,10 +15,19 @@ import (
// Site is the documentation site.
var Site = docsite.Site{
Content: content,
Content: nonVersionedFileSystem{content},
Base: &url.URL{Path: "/help/"},
}
type nonVersionedFileSystem struct{ http.FileSystem }
func (fs nonVersionedFileSystem) OpenVersion(_ context.Context, version string) (http.FileSystem, error) {
if version != "" {
return nil, errors.New("content versioning is not supported")
}
return fs.FileSystem, nil
}
// indexTemplate renders the HTML for the page index.
//
// It is rendered on the server (instead of the client) for 2 reasons: (1) because we want it to be
@ -48,8 +60,8 @@ var indexTemplate = template.Must(template.New("").Parse(`
// Register the resolver for the GraphQL field Query.docSitePage.
func init() {
graphqlbackend.DocSitePageResolver = func(args graphqlbackend.DocSitePageArgs) (graphqlbackend.DocSitePage, error) {
page, err := Site.ResolveContentPage(args.Path)
graphqlbackend.DocSitePageResolver = func(ctx context.Context, args graphqlbackend.DocSitePageArgs) (graphqlbackend.DocSitePage, error) {
page, err := Site.ResolveContentPage(ctx, "", args.Path)
if os.IsNotExist(err) {
return nil, nil
} else if err != nil {

8
cmd/frontend/graphqlbackend/doc_site.go
View File

@ -1,9 +1,11 @@
package graphqlbackend
import "context"
// DocSitePageResolver is the resolver for the GraphQL field Query.docSitePage.
//
// It is set at init time.
var DocSitePageResolver func(DocSitePageArgs) (DocSitePage, error)
var DocSitePageResolver func(context.Context, DocSitePageArgs) (DocSitePage, error)
type DocSitePageArgs struct {
Path string
@ -17,6 +19,6 @@ type DocSitePage interface {
FilePath() string
}
func (*schemaResolver) DocSitePage(args *DocSitePageArgs) (DocSitePage, error) {
return DocSitePageResolver(*args)
func (*schemaResolver) DocSitePage(ctx context.Context, args *DocSitePageArgs) (DocSitePage, error) {
return DocSitePageResolver(ctx, *args)
}

1
dev/check/all.sh
View File

@ -5,6 +5,7 @@ cd $(dirname "${BASH_SOURCE[0]}")
go version
go env
./docsite.sh
./gofmt.sh
./template-inlines.sh
./go-enterprise-import.sh

23
dev/check/docsite.sh Executable file
View File

@ -0,0 +1,23 @@
#!/bin/bash
echo "--- docsite check (lint Markdown files in doc/)"
cd "$(dirname "${BASH_SOURCE[0]}")/../.."
export GOBIN="$PWD/.bin"
export PATH=$GOBIN:$PATH
export GO111MODULE=on
go install github.com/sourcegraph/docsite/cmd/docsite
# Check broken links, etc., in Markdown files in doc/.
echo
echo
docsite check || {
echo
echo Errors found in Markdown documentation files. Fix the errors in doc/ and try again.
echo
exit 1
}

37
dev/check/docsite/doc.html Normal file
View File

@ -0,0 +1,37 @@
{{/*
This template is used only for `docsite check` (broken link checking), not for actually rendering
docs. It should emit roughly the same Markdown and links as the actual templates, to ensure that the
broken link checker checks the links that are produced by the actual templates.
- https://docs.sourcegraph.com is rendered using https://github.com/sourcegraph/docs.sourcegraph.com.
- The /help pages on a Sourcegraph instance are rendered by DocSitePage.tsx.
*/}}
{{define "root"}}
{{with .Content}}{{template "index" .}}{{end}}
{{with .Content}}
<nav class="breadcrumbs">
{{range .Breadcrumbs}}
<a href="{{.URL}}" class="{{if .IsActive}}active{{end}}">{{.Label}}</a> {{if not .IsActive}}/{{end}}
{{end}}
</nav>
{{markdown .}}
{{end}}
{{end}}
{{define "index"}}
{{with (or (and (eq (len .Doc.Tree) 1) (index .Doc.Tree 0).Children) .Doc.Tree)}}
<h4 class="visible-sm">{{$.Doc.Title}}</h4>
<ul>{{template "doc_nav" .}}</ul>
{{end}}
{{end}}
{{define "doc_nav"}}
{{range .}}
<li>
<a href="{{.URL}}">{{.Title}}</a>
{{with .Children}}
<ul>
{{template "doc_nav" .}}
</ul>
{{end}}
{{end}}
{{end}}

1
dev/go-install.sh
View File

@ -65,6 +65,7 @@ export GO111MODULE=on
if ! go install \
github.com/mattn/goreman \
github.com/derekparker/delve/cmd/dlv \
github.com/sourcegraph/docsite/cmd/docsite \
github.com/google/zoekt/cmd/zoekt-archive-index \
github.com/google/zoekt/cmd/zoekt-sourcegraph-indexserver \
github.com/google/zoekt/cmd/zoekt-webserver; then

1
dev/tools.go
View File

@ -12,6 +12,7 @@ import (
_ "github.com/kevinburke/go-bindata/go-bindata"
_ "github.com/mattn/goreman"
_ "github.com/shurcooL/vfsgen/cmd/vfsgendev"
_ "github.com/sourcegraph/docsite/cmd/docsite"
_ "github.com/sourcegraph/go-jsonschema/cmd/go-jsonschema-compiler"
_ "github.com/sourcegraph/godockerize"
_ "golang.org/x/tools/cmd/stringer"

8
doc/docsite.json Normal file
View File

@ -0,0 +1,8 @@
{
"$comment": "The actual configuration, templates, and assets for https://docs.sourcegraph.com live in https://github.com/sourcegraph/docs.sourcegraph.com. This docsite.json merely enables `docsite check` to check the doc files for common problems in this repository's CI.",
"templates": "../dev/check/docsite",
"content": ".",
"check": {
"ignoreURLPattern": "(^https?://)|(^#)|(^mailto:support@sourcegraph\\.com$)|(^chrome://)"
}
}

3
go.mod
View File

@ -99,11 +99,12 @@ require (
github.com/shurcooL/go-goon v0.0.0-20170922171312-37c2f522c041
github.com/shurcooL/httpfs v0.0.0-20171119174359-809beceb2371
github.com/shurcooL/httpgzip v0.0.0-20180522190206-b1c53ac65af9 // indirect
github.com/shurcooL/sanitized_anchor_name v1.0.0 // indirect
github.com/shurcooL/vfsgen v0.0.0-20181202132449-6a9ea43bcacd
github.com/sirupsen/logrus v1.0.6 // indirect
github.com/sloonz/go-qprintable v0.0.0-20160203160305-775b3a4592d5 // indirect
github.com/sourcegraph/ctxvfs v0.0.0-20180418081416-2b65f1b1ea81
github.com/sourcegraph/docsite v0.0.0-20181017065628-43f33608b38d
github.com/sourcegraph/docsite v0.0.0-20181231165911-11f5f871132b
github.com/sourcegraph/go-jsonschema v0.0.0-20180805125535-0e659b54484d
github.com/sourcegraph/go-langserver v2.0.1-0.20181108233942-4a51fa2e1238+incompatible
github.com/sourcegraph/go-lsp v0.0.0-20181119182933-0c7d621186c1

6
go.sum
View File

@ -429,6 +429,8 @@ github.com/shurcooL/httpgzip v0.0.0-20180522190206-b1c53ac65af9 h1:fxoFD0in0/CBz
github.com/shurcooL/httpgzip v0.0.0-20180522190206-b1c53ac65af9/go.mod h1:919LwcH0M7/W4fcZ0/jy0qGght1GIhqyS/EgWGH2j5Q=
github.com/shurcooL/sanitized_anchor_name v0.0.0-20170918181015-86672fcb3f95 h1:/vdW8Cb7EXrkqWGufVMES1OH2sU9gKVb2n9/1y5NMBY=
github.com/shurcooL/sanitized_anchor_name v0.0.0-20170918181015-86672fcb3f95/go.mod h1:1NzhyTcUVG4SuEtjjoZeVRXNmyL/1OwPU0+IJeTBvfc=
github.com/shurcooL/sanitized_anchor_name v1.0.0 h1:PdmoCO6wvbs+7yrJyMORt4/BmY5IYyJwS/kOiWx8mHo=
github.com/shurcooL/sanitized_anchor_name v1.0.0/go.mod h1:1NzhyTcUVG4SuEtjjoZeVRXNmyL/1OwPU0+IJeTBvfc=
github.com/shurcooL/vfsgen v0.0.0-20181202132449-6a9ea43bcacd h1:ug7PpSOB5RBPK1Kg6qskGBoP3Vnj/aNYFTznWvlkGo0=
github.com/shurcooL/vfsgen v0.0.0-20181202132449-6a9ea43bcacd/go.mod h1:TrYk7fJVaAttu97ZZKrO9UbRa8izdowaMIZcxYMbVaw=
github.com/sirupsen/logrus v1.0.5/go.mod h1:pMByvHTf9Beacp5x1UXfOR9xyW/9antXMhjMPG0dEzc=
@ -447,6 +449,8 @@ github.com/sourcegraph/ctxvfs v0.0.0-20180418081416-2b65f1b1ea81 h1:v4/JVxZSPWif
github.com/sourcegraph/ctxvfs v0.0.0-20180418081416-2b65f1b1ea81/go.mod h1:xIvvI5FiHLxhv8prbzVpaMHaaGPFPFQSuTcxC91ryOo=
github.com/sourcegraph/docsite v0.0.0-20181017065628-43f33608b38d h1:mOqbJXhk6waoL3rWnLee6TDX85TgZyws7vx82MwAqqk=
github.com/sourcegraph/docsite v0.0.0-20181017065628-43f33608b38d/go.mod h1:8m7AP/HZwL7m7f8RibUjr32a3AOxKDbSXMiXrds9WjM=
github.com/sourcegraph/docsite v0.0.0-20181231165911-11f5f871132b h1:L7u8laCYDilmJByMOY6cI7EeRDf4VX2M5TYCsuqxN1M=
github.com/sourcegraph/docsite v0.0.0-20181231165911-11f5f871132b/go.mod h1:KCDBpjuSIL4tk/Yv14ZIthrdijxZo4ajs256qpNsB/s=
github.com/sourcegraph/go-jsonschema v0.0.0-20180805125535-0e659b54484d h1:npjNYW9m1jUtBLMEjlfqgoTQ7cvVf1fHvITAd6TSS5s=
github.com/sourcegraph/go-jsonschema v0.0.0-20180805125535-0e659b54484d/go.mod h1:6DfNy4BLIggAeittTJ8o9z/6d1ly+YujBTSnv03i7Bk=
github.com/sourcegraph/go-langserver v2.0.1-0.20181108233942-4a51fa2e1238+incompatible h1:EX1bSaIbVia2U/Pt/2Z62y8wJS4Z4iNiK5VCeUKuBx8=
@ -455,9 +459,11 @@ github.com/sourcegraph/go-lsp v0.0.0-20181119182933-0c7d621186c1 h1:O1d7nVzpGmP5
github.com/sourcegraph/go-lsp v0.0.0-20181119182933-0c7d621186c1/go.mod h1:tpps84QRlOVVLYk5QpKYX8Tr289D1v/UTWDLqeguiqM=
github.com/sourcegraph/godockerize v0.0.0-20181126200657-4f825419611b h1:EuY/1gvLCQi/T/L9J5o6+yUe5NFRPMxzNXxc/hp7eNU=
github.com/sourcegraph/godockerize v0.0.0-20181126200657-4f825419611b/go.mod h1:EnJwbnfidbH57UXewOZLIrwQVpu/spwbS/BMN0sPfCA=
github.com/sourcegraph/gologin v1.0.2-0.20181110030308-c6f1b62954d8 h1:K7hzuWsJGoU8ILHJzrXxsuvXvLHpP/g4iUk7VFj2lY8=
github.com/sourcegraph/gologin v1.0.2-0.20181110030308-c6f1b62954d8/go.mod h1:0VfoEApmSPgPhnePllwhrB4vwCUkI0K0w8aueOgoJQI=
github.com/sourcegraph/goreman v0.1.2-0.20180928223752-6e9a2beb830d h1:FxF0pen6r1WOqbm4kVDR3JV078HfPz65inWcMh1aVQI=
github.com/sourcegraph/goreman v0.1.2-0.20180928223752-6e9a2beb830d/go.mod h1:8HCyYaC38XwX0AOu0+fuY02Y5Z7CkITW0oVJavbna4Q=
github.com/sourcegraph/gosaml2 v0.0.0-20180820053343-1b78a6b41538 h1:K6PWEK0hkyB5b5LS0JAR0VD7aMVXYtZgeQ4Jm7oMLfs=
github.com/sourcegraph/gosaml2 v0.0.0-20180820053343-1b78a6b41538/go.mod h1:ZqB/uu1WtCDmlwK8c+TO8+QSfDkJsWx9LYjQBgGxxtk=
github.com/sourcegraph/gosyntect v0.0.0-20180604231642-c01be3625b10 h1:9XH6ZJgu6KrVimEwZVXfTOvkGU1CHAvdc7mbZrMwA/U=
github.com/sourcegraph/gosyntect v0.0.0-20180604231642-c01be3625b10/go.mod h1:G6fSBYyOm5huBpPQ4qhXejeVbKeehdP7WEmwb5Si7gM=