GitSwarm-EE 2017.2-1 Documentation


Documentation styleguide

This styleguide recommends best practices to improve documentation and to keep it organized and easy to find.

Location and naming of documents

Note: These guidelines derive from the discussion taken place in issue #3349.

The documentation hierarchy can be vastly improved by providing a better layout and organization of directories.

Having a structured document layout, we will be able to have meaningful URLs like docs.gitlab.com/user/project/merge_requests.html. With this pattern, you can immediately tell that you are navigating a user related documentation and is about the project and its merge requests.

The table below shows what kind of documentation goes where.

Directory What belongs here
doc/user/ User related documentation. Anything that can be done within the GitLab UI goes here including /admin.
doc/administration/ Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed via GitLab's interface go under doc/user/admin_area/.
doc/api/ API related documentation.
doc/development/ Documentation related to the development of GitLab. Any styleguides should go here.
doc/legal/ Legal documents about contributing to GitLab.
doc/install/ Probably the most visited directory, since installation.md is there. Ideally this should go under doc/administration/, but it's best to leave it as-is in order to avoid confusion (still debated though).
doc/update/ Same with doc/install/. Should be under administration/, but this is a well known location, better leave as-is, at least for now.

General rules:

  1. The correct naming and location of a new document, is a combination of the relative URL of the document in question and the GitLab Map design that is used for UX purposes (source, image).
  2. When creating a new document and it has more than one word in its name, make sure to use underscores instead of spaces or dashes (-). For example, a proper naming would be import_projects_from_github.md. The same rule applies to images.
  3. There are four main directories, user, administration, api and development.
  4. The doc/user/ directory has five main subdirectories: project/, group/, profile/, dashboard/ and admin_area/.
  5. doc/user/project/ should contain all project related documentation.
  6. doc/user/group/ should contain all group related documentation.
  7. doc/user/profile/ should contain all profile related documentation. Every page you would navigate under /profile should have its own document, i.e. account.md, applications.md, emails.md, etc.
  8. doc/user/dashboard/ should contain all dashboard related documentation.
  9. doc/user/admin_area/ should contain all admin related documentation describing what can be achieved by accessing GitLab's admin interface (not to be confused with doc/administration where server access is required).

    1. Every category under /admin/application_settings should have its own document located at doc/user/admin_area/settings/. For example, the Visibility and Access Controls category should have a document located at doc/user/admin_area/settings/visibility_and_access_controls.md.

If you are unsure where a document should live, you can ping @axil in your merge request.

Text

Formatting

Headings

Linking to inline docs

Sometimes it's needed to link to the built-in documentation that GitLab provides under /help. This is normally done in files inside the app/views/ directory with the help of the help_page_path helper method.

In its simplest form, the HAML code to generate a link to the /help page is:

= link_to 'Help page', help_page_path('user/permissions')

The help_page_path contains the path to the document you want to link to with the following conventions:

Below are some special cases where should be used depending on the context. You can combine one or more of the following:

  1. Linking to an anchor link. Use anchor as part of the help_page_path method:

    = link_to 'Help page', help_page_path('user/permissions', anchor: 'anchor-link')
  2. Opening links in a new tab. This should be the default behavior:

    = link_to 'Help page', help_page_path('user/permissions'), target: '_blank'
  3. Linking to a circle icon. Usually used in settings where a long description cannot be used, like near checkboxes. You can basically use any font awesome icon, but prefer the question-circle:

    = link_to icon('question-circle'), help_page_path('user/permissions')
  4. Using a button link. Useful in places where text would be out of context with the rest of the page layout:

    = link_to 'Help page', help_page_path('user/permissions'),  class: 'btn btn-info'
  5. Underlining a link.

    = link_to 'Help page', help_page_path('user/permissions'), class: 'underlined-link'
  6. Using links inline of some text.

    Description to #{link_to 'Help page', help_page_path('user/permissions')}.
  7. Adding a period at the end of the sentence. Useful when you don't want the period to be part of the link:

    = succeed '.' do
      Learn more in the
      = link_to 'Help page', help_page_path('user/permissions')

Images

Inside the document:

Notes

New features

References

Installation guide

Changing document location

Changing a document's location is not to be taken lightly. Remember that the documentation is available to all installations under help/ and not only to GitLab.com or http://docs.gitlab.com. Make sure this is discussed with the Documentation team beforehand.

If you indeed need to change a document's location, do NOT remove the old document, but rather put a text in it that points to the new location, like:

This document was moved to [path/to/new_doc.md](path/to/new_doc.md).

where path/to/new_doc.md is the relative path to the root directory doc/.


For example, if you were to move doc/workflow/lfs/lfs_administration.md to doc/administration/lfs.md, then the steps would be:

  1. Copy doc/workflow/lfs/lfs_administration.md to doc/administration/lfs.md
  2. Replace the contents of doc/workflow/lfs/lfs_administration.md with:

    This document was moved to [administration/lfs.md](../../administration/lfs.md).
  3. Find and replace any occurrences of the old location with the new one. A quick way to find them is to use git grep. First go to the root directory where you cloned the gitlab-ce repository and then do:

    git grep -n "workflow/lfs/lfs_administration"
    git grep -n "lfs/lfs_administration"

Things to note:

Configuration documentation for source and Omnibus installations

GitLab currently officially supports two installation methods: installations from source and Omnibus packages installations.

Whenever there is a setting that is configurable for both installation methods, prefer to document it in the CE docs to avoid duplication.

Configuration settings include:

When there is a list of steps to perform, usually that entails editing the configuration file and reconfiguring/restarting GitLab. In such case, follow the style below as a guide:

**For Omnibus installations**

1. Edit `/etc/gitlab/gitlab.rb`:

    ```ruby
    external_url "https://gitlab.example.com"
    ```

1. Save the file and [reconfigure] GitLab for the changes to take effect.

---

**For installations from source**

1. Edit `config/gitlab.yml`:

    ```yaml
    gitlab:
      host: "gitlab.example.com"
    ```

1. Save the file and [restart] GitLab for the changes to take effect.


[reconfigure]: path/to/administration/gitlab_restart.md#omnibus-gitlab-reconfigure
[restart]: path/to/administration/gitlab_restart.md#installations-from-source

In this case:

Fake tokens

There may be times where a token is needed to demonstrate an API call using cURL or a secret variable used in CI. It is strongly advised not to use real tokens in documentation even if the probability of a token being exploited is low.

You can use the following fake tokens as examples.

Token type Token value
Private user token 9koXpg98eAheJpvBs5tK
Personal access token n671WNGecHugsdEDPsyo
Application ID 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
Application secret 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
Secret CI variable Li8j-mLUVA3eZYjPfd_H
Specific Runner token yrnZW46BrtBFqM7xDzE7dddd
Shared Runner token 6Vk7ZsosqQyfreAxXTZr
Trigger token be20d8dcc028677c931e04f3871a9b
Webhook secret token 6XhDroRcYPM5by_h-HLY
Health check token Tu7BgjR9qeZTEyRzGG2P
Request profile token 7VgpS4Ax5utVD2esNstz

API

Here is a list of must-have items. Use them in the exact order that appears on this document. Further explanation is given below.

Method description

Use the following table headers to describe the methods. Attributes should always be in code blocks using backticks (`).

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |

Rendered example:

Attribute Type Required Description
user string yes The GitLab username

cURL commands

Methods Description
-H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" Use this method as is, whenever authentication needed
-X POST Use this method when creating new objects
-X PUT Use this method when updating existing objects
-X DELETE Use this method when removing existing objects

cURL Examples

Below is a set of cURL examples that you can use in the API documentation.

Simple cURL command

Get the details of a group:

curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/gitlab-org

cURL example with parameters passed in the URL

Create a new project under the authenticated user's namespace:

curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects?name=foo"

Post data using cURL's --data

Instead of using -X POST and appending the parameters to the URI, you can use cURL's --data option. The example below will create a new project foo under the authenticated user's namespace.

curl --data "name=foo" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects"

Post data using JSON content

Note: In this example we create a new group. Watch carefully the single and double quotes.

curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' https://gitlab.example.com/api/v3/groups

Post data using form-data

Instead of using JSON or urlencode you can use multipart/form-data which properly handles data encoding:

curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "title=ssh-key" --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." https://gitlab.example.com/api/v3/users/25/keys

The above example is run by and administrator and will add an SSH public key titled ssh-key to user's account which has an id of 25.

Escape special characters

Spaces or slashes (/) may sometimes result to errors, thus it is recommended to escape them when possible. In the example below we create a new issue which contains spaces in its title. Observe how spaces are escaped using the %20 ASCII code.

curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/42/issues?title=Hello%20Dude"

Use %2F for slashes (/).

Pass arrays to API calls

The GitLab API sometimes accepts arrays of strings or integers. For example, to restrict the sign-up e-mail domains of a GitLab instance to *.example.com and example.net, you would do something like this:

curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "domain_whitelist[]=*.example.com" --data "domain_whitelist[]=example.net" https://gitlab.example.com/api/v3/application/settings