Commit 87843145 authored by Thomas Boni's avatar Thomas Boni
Browse files

Merge branch '17-new-job-build-documentation-with-apidocjs' into 'latest' 

Resolve "New job - build documentation with apidocjs"

Closes #17

See merge request go2scale/hub!11
parents b7957c30 7316e6f0

.gitlab-ci.yml

+0 −6
Original line number Diff line number Diff line
@@ -14,9 +14,6 @@ documentation: 
    expose_as: "Documentation"

    paths:

    - public/

  except:

    variables:

      - $DOCUMENTATION_DISABLE



pages:

  stage: production
@@ -30,6 +27,3 @@ pages: 
    - public

  only:

    - latest
 
  except:

    variables:

      - $DOCUMENTATION_DISABLE || $PAGES_DISABLE

docs/jobs/build/apidoc.md

0 → 100644
+54 −0
Original line number Diff line number Diff line 
# 📒 ApiDoc



## Description



Creates a versioned HTML documentation from API annotations in your source

code using [apiDoc](https://www.apidocjs.com/).



## How to use it



1. Prepare your project with API annotations in your source code following

   [apiDoc format](https://apidocjs.com/#examples) and your [apiDoc

   configuration file](https://apidocjs.com/#configuration).

2. Choose a version in [version list](#versions)

3. Add the corresponding URL to your `.gitlab-ci.yml` file (see [Getting

   started](/getting-started)). Example:



    ```yaml

    include:

      - remote: 'https://jobs.go2scale.io/apidoc.yml'

    ```



4. If you need to customize the job (stage, variables, ...) 👉 check the [jobs

   customization](/getting-started/#jobs-customization)

5. Well done, your job is ready to work ! 😀



## Job details



* Job name: `documentation`

* Docker image:

[`node`](https://hub.docker.com/r/_/node)

* Default stage: `build`

* When: `always`



### Variables



| Name | Description | Default |

| ---- | ----------- | ------- |

| `APIDOC_VERSION` | Version of apiDoc to use | `0.24.0` |

| `APIDOC_CONFIG_PATH` | Path to config file or to directory containing config file (apidoc.json or apidoc.config.js) | `.` |

| `APIDOC_OUTPUT_PATH` | Output directory path | `/apidoc_build` |

| `APIDOC_TEMPLATE_PATH` | Path to template folder | `/usr/lib/node_modules/apidoc/template/` |



### Artifacts



Result of documentation build is [exposed

as](https://docs.gitlab.com/ee/ci/yaml/#artifactsexpose_as) `apiDoc build` in

merge requests.



## Versions



* **Latest** (current -> `2020-08-07_1`) : `https://jobs.go2scale.io/latest/apidoc.yml`

* **Tag `2020-08-07_1`** : `https://jobs.go2scale.io/2020-08-07_1/apidoc.yml`



    * Initial version

docs/jobs/build/mkdocs.md

+3 −9
Original line number Diff line number Diff line
@@ -33,18 +33,12 @@ Mkdocs](https://squidfunk.github.io/mkdocs-material/) are ready to use. 


## Job details



* Job name: `mkdocs`

* Job name: `documentation`

* Docker image:

[`squidfunk/mkdocs-material`](https://hub.docker.com/r/squidfunk/mkdocs-material)

* Default stage: `build`

* When: `always`



### Variables



| Name | Description | Default |

| ---- | ----------- | ------- |

| `DOCUMENTATION_DISABLE` | Disable build | |



### Artifacts



Result of documentation build is [exposed
@@ -53,8 +47,8 @@ merge requests 


## Versions



* **Latest** (current -> `2020-08-05_2`) : `https://jobs.go2scale.io/latest/mkdocs.yml`

* **Tag `2020-08-05_2`** : `https://jobs.go2scale.io/2020-08-05_2/mkdocs.yml`

* **Latest** (current -> `2020-08-05_1`) : `https://jobs.go2scale.io/latest/mkdocs.yml`

* **Tag `2020-08-05_1`** : `https://jobs.go2scale.io/2020-08-05_1/mkdocs.yml`



    !!! warning

        Since this version, `pages` job, which publish documentation on Gitlab

docs/jobs/deployment/pages.md

+1 −4
Original line number Diff line number Diff line
@@ -33,12 +33,9 @@ from previous job named `documentation`. 
* Stage: `deployment`

* When: only run on `master` branch



### Variables:



| Name | Description | Default |

| ---- | ----------- | ------- |

| `DOCUMENTATION_DISABLE` | Disable publication on Gitlab pages| |

| `PAGES_DISABLE` | Disable publication on Gitlab pages | |

| `PAGES_BUILD_PATH` | Path to folder which contains documentation build | |



## Versions

docs/jobs/index.md

+1 −0
Original line number Diff line number Diff line
@@ -12,6 +12,7 @@ Jobs index. They are sorted using the [HUB default stages](/getting-started#stag 


| Name | Description |

| ---- | ----------- |

| 📒 [ApiDoc](/jobs/build/apidoc) | Creates a HTML documentation from API annotations in source code |

| 🐳 [Docker](/jobs/build/docker) | Build and publish Docker image using Kaniko |

| 📃 [Mkdocs](/jobs/build/mkdocs) | Build documentation from markdown to HTML using Mkdocs|