diff options
Diffstat (limited to 'doc/development/documentation/index.md')
| -rw-r--r-- | doc/development/documentation/index.md | 272 |
1 files changed, 5 insertions, 267 deletions
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index e51f966ee6e..69a8ff10878 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -11,7 +11,7 @@ GitLab's documentation is [intended as the single source of truth (SSOT)](https: In addition to this page, the following resources can help you craft and contribute to documentation: -- [Style Guide](styleguide.md) - What belongs in the docs, language guidelines, Markdown standards to follow, links, and more. +- [Style Guide](styleguide/index.md) - What belongs in the docs, language guidelines, Markdown standards to follow, links, and more. - [Structure and template](structure.md) - Learn the typical parts of a doc page and how to write each one. - [Documentation process](workflow.md). - [Markdown Guide](../../user/markdown.md) - A reference for all Markdown syntax supported by GitLab. @@ -64,11 +64,11 @@ However, anyone can contribute [documentation improvements](workflow.md) that ar [GitLab docs](https://gitlab.com/gitlab-org/gitlab-docs) uses [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown) as its Markdown rendering engine. See the [GitLab Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/) for a complete Kramdown reference. -Adhere to the [Documentation Style Guide](styleguide.md). If a style standard is missing, you are welcome to suggest one via a merge request. +Adhere to the [Documentation Style Guide](styleguide/index.md). If a style standard is missing, you are welcome to suggest one via a merge request. ## Folder structure and files -See the [Structure](styleguide.md#structure) section of the [Documentation Style Guide](styleguide.md). +See the [Structure](styleguide/index.md#structure) section of the [Documentation Style Guide](styleguide/index.md). ## Metadata @@ -229,7 +229,7 @@ Things to note: it in for `workflow/lfs/lfs_administration` and `lfs/lfs_administration` and will print the file and the line where this file is mentioned. You may ask why the two greps. Since [we use relative paths to link to - documentation](styleguide.md#links), sometimes it might be useful to search a path deeper. + documentation](styleguide/index.md#links), sometimes it might be useful to search a path deeper. - The `*.md` extension is not used when a document is linked to GitLab's built-in help page, which is why we omit it in `git grep`. - Use the checklist on the "Change documentation location" MR description template. @@ -472,269 +472,7 @@ The following GitLab features are used among others: ## Testing -We treat documentation as code, and so use tests in our CI pipeline to maintain the -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: - -- [`docs lint`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L41): - 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) - 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). - - [Vale](#vale). - - Nanoc tests: - - [`internal_links`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L58) - checks that all internal links (ex: `[link](../index.md)`) are valid. - - [`internal_anchors`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L60) - checks that all internal anchors (ex: `[link](../index.md#internal_anchor)`) - are valid. - - [`ui-docs-links lint`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L62) - checks that all links to docs from UI elements (`app/views` files, for example) - are linking to valid docs and anchors. - -### Run tests locally - -Apart from [previewing your changes locally](#previewing-the-changes-live), you can also run all lint checks -and Nanoc tests locally. - -#### 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: - -```plaintext -=> 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. - -#### 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 - ``` - -#### `ui-docs-links` test - -The `ui-docs-links lint` job uses `haml-lint` to test that all links to docs from -UI elements (`app/views` files, for example) are linking to valid docs and anchors. - -To run the `ui-docs-links` test locally: - -1. Open the `gitlab` directory in a terminal window. -1. Run: - - ```shell - bundle exec haml-lint -i DocumentationLinks - ``` - -If you receive an error the first time you run this test, run `bundle install`, which -installs GitLab's dependencies, and try again. - -If you don't want to install all of GitLab's dependencies to test the links, you can: - -1. Open the `gitlab` directory in a terminal window. -1. Install `haml-lint`: - - ```shell - gem install haml_lint - ``` - -1. Run: - - ```shell - haml-lint -i DocumentationLinks - ``` - -If you manually install `haml-lint` with this process, it will not update automatically -and you should make sure your version matches the version used by GitLab. - -### Local linters - -To help adhere to the [documentation style guidelines](styleguide.md), and improve the content -added to documentation, [install documentation linters](#install-linters) and -[integrate them with your code editor](#configure-editors). - -At GitLab, we mostly use: - -- [markdownlint](#markdownlint) -- [Vale](#vale) - -#### markdownlint - -[markdownlint](https://github.com/DavidAnson/markdownlint) checks that Markdown syntax follows -[certain rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules), and is -used by the [`docs-lint` test](#testing). - -Our [Documentation Style Guide](styleguide.md#markdown) and -[Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/) elaborate on which choices must -be made when selecting Markdown syntax for GitLab documentation. This tool helps catch deviations -from those guidelines. - -markdownlint configuration is found in the following projects: - -- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.markdownlint.json) -- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/.markdownlint.json) -- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.markdownlint.json) -- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.markdownlint.json) -- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/.markdownlint.json) - -This configuration is also used within build pipelines. - -You can use markdownlint: - -- [On the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--). -- [Within a code editor](#configure-editors). -- [In a `pre-commit` hook](#configure-pre-commit-hooks). - -#### Vale - -[Vale](https://errata-ai.gitbook.io/vale/) is a grammar, style, and word usage linter for the -English language. Vale's configuration is stored in the -[`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) file located in the root -directory of projects. - -Vale supports creating [custom tests](https://errata-ai.github.io/vale/styles/) that extend any of -several types of checks, which we store in the `.linting/vale/styles/gitlab` directory within the -documentation directory of projects. - -Vale configuration is found in the following projects: - -- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab) -- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/master/docs/.vale/gitlab) -- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/tree/master/doc/.vale/gitlab) -- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/tree/master/doc/.vale/gitlab) -- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/master/doc/.vale/gitlab) - -This configuration is also used within build pipelines. - -You can use Vale: - -- [On the command line](https://errata-ai.gitbook.io/vale/getting-started/usage). -- [Within a code editor](#configure-editors). -- [In a `pre-commit` hook](#configure-pre-commit-hooks). Vale only reports errors in the - `pre-commit` hook (the same configuration as the CI/CD pipelines), and does not report suggestions - or warnings. - -#### Install linters - -At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in -build pipelines: - -1. Install `markdownlint-cli`, using either: - - - `npm`: - - ```shell - npm install -g markdownlint-cli - ``` - - - `yarn`: - - ```shell - yarn global add markdownlint-cli - ``` - - We recommend installing the version of `markdownlint-cli` currently used in the documentation - linting [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L420). - -1. Install [`vale`](https://github.com/errata-ai/vale/releases). For example, to install using - `brew` for macOS, run: - - ```shell - brew install vale - ``` - - We recommend installing the version of Vale currently used in the documentation linting - [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L419). - -In addition to using markdownlint and Vale at the command line, these tools can be -[integrated with your code editor](#configure-editors). - -#### Configure editors - -To configure markdownlint within your editor, install one of the following as appropriate: - -- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) -- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) -- [Atom](https://atom.io/packages/linter-node-markdownlint) -- [Vim](https://github.com/dense-analysis/ale) - -To configure Vale within your editor, install one of the following as appropriate: - -- The Sublime Text [`SublimeLinter-contrib-vale` plugin](https://packagecontrol.io/packages/SublimeLinter-contrib-vale). -- The Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server). You don't need Vale Server to use the plugin. -- [Vim](https://github.com/dense-analysis/ale). - -We don't use [Vale Server](https://errata-ai.github.io/vale/#using-vale-with-a-text-editor-or-another-third-party-application). - -#### Configure pre-commit hooks - -Git [pre-commit hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) allow Git users to -run tests or other processes before committing to a branch, with the ability to not commit to the branch if -failures occur with these tests. - -[`overcommit`](https://github.com/sds/overcommit) is a Git hooks manager, making configuring, -installing, and removing Git hooks easy. - -Sample configuration for `overcommit` is available in the -[`.overcommit.yml.example`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.overcommit.yml.example) -file for the [`gitlab`](https://gitlab.com/gitlab-org/gitlab) project. - -To set up `overcommit` for documentation linting, see -[Pre-commit static analysis](../contributing/style_guides.md#pre-commit-static-analysis). - -#### Disable Vale tests - -You can disable a specific Vale linting rule or all Vale linting rules for any portion of a -document: - -- To disable a specific rule, add a `<!-- vale gitlab.rulename = NO -->` tag before the text, and a - `<!-- vale gitlab.rulename = YES -->` tag after the text, replacing `rulename` with the filename - of a test in the - [GitLab styles](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.linting/vale/styles/gitlab) - directory. -- To disable all Vale linting rules, add a `<!-- vale off -->` tag before the text, and a - `<!-- vale on -->` tag after the text. - -Whenever possible, exclude only the problematic rule and line(s). - -For more information, see -[Vale's documentation](https://errata-ai.gitbook.io/vale/getting-started/markup#markup-based-configuration). +For more information on documentation testing, see [Documentation testing](testing.md) ## Danger Bot |