diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-03-05 15:07:48 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-03-05 15:07:48 +0300 |
commit | 5a6b36b60502c50ab59c0bc3c345793b70a3d548 (patch) | |
tree | 7cf2effbd48359b44970f8f345cfa12ce6843dfd /doc/development/documentation/index.md | |
parent | a76d34e6716aa8267111ecdcd21416e9dec3a08d (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/development/documentation/index.md')
-rw-r--r-- | doc/development/documentation/index.md | 63 |
1 files changed, 58 insertions, 5 deletions
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 4fcdd8a1fb0..694acc16a97 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -393,15 +393,14 @@ merge request with new or changed docs is submitted, are: - [`docs lint`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/docs.gitlab-ci.yml#L48): Runs several tests on the content of the docs themselves: - [`lint-doc.sh` script](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) - checks that: + runs the following checks and linters: - All cURL examples use the long flags (ex: `--header`, not `-H`). - The `CHANGELOG.md` does not contain duplicate versions. - 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: + - [markdownlint](#markdownlint). + - [Vale](#vale). + - Nanoc tests: - [`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) @@ -410,6 +409,60 @@ merge request with new or changed docs is submitted, are: - If any code or the `doc/README.md` file is changed, a full pipeline will run, which runs tests for [`/help`](#gitlab-help-tests). +### Running tests & lint checks locally + +Apart from [previewing your changes locally](#previewing-the-changes-live), you can also run all lint checks +and Nanoc tests locally. + +#### Nanoc tests + +To execute Nanoc tests locally: + +1. Navigate to the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. +1. Run: + + ```shell + # Check for broken internal links + bundle exec nanoc check internal_links + + # Check for broken external links (might take a lot of time to complete). + # This test is set to be allowed to fail and is run only in the gitlab-docs project CI + bundle exec nanoc check internal_anchors + ``` + +#### Lint checks + +Lint checks are performed by the [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) +script and can be executed as follows: + +1. Navigate to the `gitlab` directory. +1. Run: + + ```shell + MD_DOC_PATH=path/to/my_doc.md scripts/lint-doc.sh + ``` + +Where `MD_DOC_PATH` points to the file or directory you would like to run lint checks for. +If you omit it completely, it will default to the `doc/` directory. +The output should be similar to: + +``` +=> Linting documents at path /path/to/gitlab as <user>... +=> Checking for cURL short options... +=> Checking for CHANGELOG.md duplicate entries... +=> Checking /path/to/gitlab/doc for executable permissions... +=> Checking for new README.md files... +=> Linting markdown style... +=> Linting prose... +✔ 0 errors, 0 warnings and 0 suggestions in 1 file. +✔ Linting passed +``` + +Note that this requires you to either have the required lint tools installed on your machine, +or a working Docker installation, in which case an image with these tools pre-installed will be used. + +For more information on available linters refer to the [linting](#linting) section. + ### Linting To help adhere to the [documentation style guidelines](styleguide.md), and improve the content |