Commit 1a683706 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis 🚀

Add basic support for running the docs site locally

parent 51cd5ea9
......@@ -60,3 +60,4 @@
/gitlab-workhorse/.cache
/go-gitlab-shell
/.gitaly-ruby-bundle
/gitlab-docs
......@@ -7,6 +7,7 @@ gitlab_workhorse_repo = https://gitlab.com/gitlab-org/gitlab-workhorse.git
gitlab_workhorse_clone_dir = gitlab-workhorse/src/gitlab.com/gitlab-org/gitlab-workhorse
gitaly_repo = https://gitlab.com/gitlab-org/gitaly.git
gitaly_clone_dir = gitaly/src/gitlab.com/gitlab-org/gitaly
gitlab_docs_repo = https://gitlab.com/gitlab-com/gitlab-docs.git
gitlab_development_root = $(shell pwd)
postgres_bin_dir = $(shell pg_config --bindir)
postgres_replication_user = gitlab_replication
......@@ -118,6 +119,33 @@ gitaly/ruby:
cd gitaly/ruby && bundle install
touch $@
# Set up gitlab-docs
gitlab-docs-setup: gitlab-docs/.git gitlab-docs-bundle gitlab-docs/nanoc.yaml symlink-gitlab-docs
gitlab-docs/.git:
git clone ${gitlab_docs_repo} gitlab-docs
gitlab-docs/.git/pull:
cd gitlab-docs && \
git stash && \
git checkout master &&\
git pull --ff-only
# We need PHONY since there's already a nanoc.yaml file
# in the docs folder which we need to overwrite.
.PHONY: gitlab-docs/nanoc.yaml
gitlab-docs/nanoc.yaml:
cp nanoc.yaml.example $@
gitlab-docs-bundle:
cd ${gitlab_development_root}/gitlab-docs && bundle install --jobs 4
symlink-gitlab-docs:
support/symlink-gitlab-shell ${gitlab_development_root}/gitlab-docs/content/docs ${gitlab_development_root}/gitlab/doc
gitlab-docs-update: gitlab-docs/.git/pull gitlab-docs-bundle
# Update gitlab, gitlab-shell, gitlab-workhorse and gitaly
update: unlock-dependency-installers gitlab-update gitlab-shell-update gitlab-workhorse-update gitaly-update
......
......@@ -33,3 +33,4 @@ to learn how to develop GitLab CE.
- [SSH](ssh.md)
- [Using GitLab Runner with GDK](runner.md)
- [Using Prometheus with GDK](prometheus.md)
- [Preview and test the docs site locally](gitlab_docs.md)
# Setting up GitLab Docs
Our CI includes [some checks][lint] for the documentation in GitLab. In order
to run the relative links checks locally or preview the changes, do the following:
1. Pull the `gitlab-docs` repo:
```
make gitlab-docs-setup
```
1. Change directory:
```
cd gitlab-docs/
```
1. Create the HTML files:
```
bundle exec rake nanoc
```
1. Run the internal links check:
```
bundle exec nanoc check internal_links
```
1. (Optionally) Preview the docs site locally:
```
bundle exec nanoc -p 3005
```
Visit <http://localhost:3005>
[lint]: https://docs.gitlab.com/ee/development/writing_documentation.html#testing
# The syntax to use for patterns in the Rules file. Can be either `"glob"`
# (default) or `"legacy"`. The former will enable glob patterns, which behave
# like Ruby’s File.fnmatch. The latter will enable Nanoc 3.x-style patterns.
string_pattern_type: glob
# A list of file extensions that Nanoc will consider to be textual rather than
# binary. If an item with an extension not in this list is found, the file
# will be considered as binary.
text_extensions: [ 'adoc', 'asciidoc', 'atom', 'coffee', 'css', 'erb', 'haml', 'handlebars', 'hb', 'htm', 'html', 'js', 'less', 'markdown', 'md', 'ms', 'mustache', 'php', 'rb', 'rdoc', 'sass', 'scss', 'slim', 'txt', 'xhtml', 'xml' ]
# The path to the directory where all generated files will be written to. This
# can be an absolute path starting with a slash, but it can also be path
# relative to the site directory.
output_dir: public
# A list of index filenames, i.e. names of files that will be served by a web
# server when a directory is requested. Usually, index files are named
# “index.html”, but depending on the web server, this may be something else,
# such as “default.htm”. This list is used by Nanoc to generate pretty URLs.
index_filenames: [ 'index.html' ]
# Whether or not to generate a diff of the compiled content when compiling a
# site. The diff will contain the differences between the compiled content
# before and after the last site compilation.
enable_output_diff: false
base_url: https://docs.gitlab.com
prune:
# Whether to automatically remove files not managed by Nanoc from the output
# directory.
auto_prune: true
# Which files and directories you want to exclude from pruning. If you version
# your output directory, you should probably exclude VCS directories such as
# .git, .svn etc.
exclude: [ '.git', '.hg', '.svn', 'CVS' ]
# The data sources where Nanoc loads its data from. This is an array of
# hashes; each array element represents a single data source. By default,
# there is only a single data source that reads data from the “content/” and
# “layout/” directories in the site directory.
data_sources:
-
# The type is the identifier of the data source.
type: filesystem
# The path where items should be mounted (comparable to mount points in
# Unix-like systems). This is “/” by default, meaning that items will have
# “/” prefixed to their identifiers. If the items root were “/en/”
# instead, an item at content/about.html would have an identifier of
# “/en/about/” instead of just “/about/”.
items_root: /
# The path where layouts should be mounted. The layouts root behaves the
# same as the items root, but applies to layouts rather than items.
layouts_root: /
# The encoding to use for input files. If your input files are not in
# UTF-8 (which they should be!), change this.
encoding: utf-8
# The kind of identifier to use for items and layouts. The default is
# “full”, meaning that identifiers include file extensions. This can also
# be “legacy”, primarily used by older Nanoc sites.
identifier_type: full
# Configuration for the “check” command, which run unit tests on the site.
checks:
# Configuration for the “internal_links” checker, which checks whether all
# internal links are valid.
internal_links:
# A list of patterns, specified as regular expressions, to exclude from the check.
# If an internal link matches this pattern, the validity check will be skipped.
# E.g.:
# exclude: ['^/server_status']
exclude: []
# Configuration for the “external_links” checker, which checks whether all
# external links are valid.
external_links:
# A list of patterns, specified as regular expressions, to exclude from the check.
# If an external link matches this pattern, the validity check will be skipped.
# E.g.:
# exclude: ['^http://example.com$']
exclude: ['http:\/\/127\.0\.0\.1:3000.*', 'http:\/\/www\.amazon\.com\/.*', 'http:\/\/www\.amazon\.co\.uk\/.*', 'http:\/\/192\.168\.59\.103']
# A list of file patterns, specified as regular expressions, to exclude from the check.
# If a file matches this pattern, the links from this file will not be checked.
# E.g.:
# exclude_files: ['blog/page']
exclude_files: []
# Whether or not breadcrumbs are enabled.
# Breadcrumbs are enabled.
breadcrumbs: true
# Debug problems with the generation process by setting this config variable.
debug: false
products:
docs:
full_name: 'GitLab Docs'
short_name: 'GitLab Docs'
slug: 'docs'
index_file: 'README.*'
description: 'Browse user and administration documentation and guides for GitLab Community Edition.'
expose: true
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment