Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
G
gitlab-ce
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
1
Merge Requests
1
Analytics
Analytics
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Commits
Issue Boards
Open sidebar
nexedi
gitlab-ce
Commits
f7d998bc
Commit
f7d998bc
authored
Oct 11, 2019
by
Marcel Amirault
Committed by
Achilleas Pipinellis
Oct 11, 2019
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Update docs linting details
parent
fe6c7d5f
Changes
1
Show whitespace changes
Inline
Side-by-side
Showing
1 changed file
with
27 additions
and
12 deletions
+27
-12
doc/development/documentation/index.md
doc/development/documentation/index.md
+27
-12
No files found.
doc/development/documentation/index.md
View file @
f7d998bc
...
@@ -374,17 +374,29 @@ The following GitLab features are used among others:
...
@@ -374,17 +374,29 @@ The following GitLab features are used among others:
## Testing
## Testing
We treat documentation as code, and so use tests to maintain the standards and quality of the docs.
We treat documentation as code, and so use tests in our CI pipeline to maintain the
The current tests are:
standards and quality of the docs. The current tests, which run in CI jobs when a
merge request with new or changed docs is submitted, are:
1. `docs lint`: Check that all internal (relative) links work correctly and
that all cURL examples in API docs use the full switches. It's recommended
- [`docs lint`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/docs.gitlab-ci.yml#L48):
to [check locally](#previewing-the-changes-live) before pushing to GitLab by executing the command
Runs several tests on the content of the docs themselves:
`bundle exec nanoc check internal_links` on your local
- [`lint-doc.sh` script](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh)
[`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. In addition,
checks that:
`docs-lint` also runs [`markdownlint`](#markdownlint) to ensure the
- All cURL examples use the long flags (ex: `--header`, not `-H`).
markdown is consistent across all documentation.
- The `CHANGELOG.md` does not contain duplicate versions.
1. In a full pipeline, tests for [`/help`](#gitlab-help-tests).
- No files in `doc/` are executable.
- No new `README.md` was added.
- [`markdownlint`](#markdownlint).
- Nanoc tests, which you can [run locally](#previewing-the-changes-live) before
pushing to GitLab by executing the command `bundle exec nanoc check internal_links`
(or `internal_anchors`) on your local [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory:
- [`internal_links`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/docs.gitlab-ci.yml#L67)
checks that all internal links (ex: `[link](../index.md)`) are valid.
- [`internal_anchors`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/docs.gitlab-ci.yml#L69)
checks that all internal anchors (ex: `[link](../index.md#internal_anchor)`)
are valid.
- If any code or the `doc/README.md` file is changed, a full pipeline will run, which
runs tests for [`/help`](#gitlab-help-tests).
### Linting
### Linting
...
@@ -490,7 +502,10 @@ four repos that are the sources for <https://docs.gitlab.com>:
...
@@ -490,7 +502,10 @@ four repos that are the sources for <https://docs.gitlab.com>:
- <https://gitlab.com/charts/gitlab/blob/master/.markdownlint.json>
- <https://gitlab.com/charts/gitlab/blob/master/.markdownlint.json>
By default all rules are enabled, so the configuration file is used to disable unwanted
By default all rules are enabled, so the configuration file is used to disable unwanted
rules, and also to configure optional parameters for enabled rules as needed.
rules, and also to configure optional parameters for enabled rules as needed. You can
also check [the issue](https://gitlab.com/gitlab-org/gitlab-foss/issues/64352) that
tracked the changes required to implement these rules, and details which rules were
on or off when `markdownlint` was enabled on the docs.
## Danger Bot
## Danger Bot
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment