# How to build publish code documentation on GitLab

This article will show how to build TS documentation with GitLab CI & deploy it on GitLab pages. The advantage of this approach is that we don't need additional credentials or user management if we want to keep access to documentation limited. We can set the documentation to be available only to people who have access to the code.

# The code

The code I'll be documenting is a simple TS file, `src/index.ts`:
```ts
/**
 * Class that contains contact information
 */
export class Contact {
  /**
   * Phone number, with or without country code.
   */
  public phoneNumber: string;

  public firstName: string;

  public lastName: string;
}

/**
 * Loads contacts from the database.
 * @returns all contacts
 */
export function getContacts(): Contact[] {
  throw new Error("Not implemented");
}
```

Here we will have an example of class & function documentations.

## Dependencies

To building the doc, I'm using [TypeDoc](https://typedoc.org/). First, I needed to turn the folder into an npm package:
```
$ npm init -y
```
then install dependency:
```
$ npm install typedoc --save-dev

added 29 packages, and audited 30 packages in 3s

1 package is looking for funding
  run `npm fund` for details

found 0 vulnerabilities
```
and add doc building script to `package.json`:
```JSON
{
  ...
  "scripts": {
    ...
    "docs": "typedoc src/index.ts"
  },
  ...
}
```

TypeDoc does require `tsconfig.json` to work correctly. A simple one that works in our case:
```JSON
{
  "compilerOptions": {
    "module": "ESNext"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}
```

## Local test
With all the configuration in place, it should already be working locally. We can check it with:
```sh
npm run docs

> self-hosted-doc@1.0.0 docs
> typedoc src/index.ts

Rendering [========================================] 100%
Info: Documentation generated at /home/marcin/workspace/github/self-hosted-doc/docs
```

# The CI configuration
For the build & deployment on GitLab, we need `.gitlab-ci.yml` as follow:

```yml
stages:
  - deploy
```

Definition of stages for our job(s). In this example, we are fine with just one, deploy, but in a more complex project, it can make sense to, for example, build the doc along with compiling the TS.

```yml
pages:
```
For the GitLab pages to deploy, there are few things our configuration has to match. One of them is the job has to be called `pages`. Publishing some build output accidentally could leak data that should have been private, so this is made a bit complicated to help protect the users.

```yml
  stage: deploy
  image: node:16
```

Stage as was defined earlier, and some node image to build the doc.

```yml
  artifacts:
    paths:
      - public
```

Another configuration that has to match - GitLab will publish the content of the `public` folder to the pages, and we have to set it up as an artifact.

```yml
  script:
    - npm ci
    - npm run docs
    - mv docs public
```

Dependency installation & build. `mv docs public` moves the doc output to the `public` directory.

## Complete `.gitlab-ci.yml`

```yml
stages:
  - deploy

pages:
  stage: deploy
  image: node:16
  artifacts:
    paths:
      - public
  script:
    - npm ci
    - npm run docs
    - mv docs public
```

# Settings
There isn't anything to set up in the configuration for this to work. In my example, I on `https://gitlab.com/marcin-wosinek/self-hosted-doc/pages` I can add a domain or remove the page:

![setting-after-deploy.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1627883805644/myU0vwS60.png)

The access settings are on the general settings page - https://gitlab.com/marcin-wosinek/self-hosted-doc/edit, and you need to open **Visibility, project features, permissions** section:

![settings-header.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1627883880907/BgJZEmvWa.png)

and then look for **Pages**:

![setting-switch.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1627883917092/9D6i--jms.png)

# Links

[The working documentation](https://marcin-wosinek.gitlab.io/self-hosted-doc/) & [the example repository](https://marcin-wosinek.gitlab.io/self-hosted-doc/).

# Summary
In this article, we have seen how to build & deploy code documentation in GitLab.

%%[gitlab]