Cheetah - SKA - PSS - Prototype Time Domain Search Pipeline
doc/publishing.md
1 # API Documentation Publishing
2 
3 The API documents are published automatically to gitlab pages on a push to the master branch of the repository.
4 
5 This process is driven by the file *.gitlab-ci.yml* which defines a pipeline of jobs that are run on a *'runner'*. Runners run in *docker* containers, and the YAML file defines how this container is set up for each job.
6 
7 To publish the documentation there are 2 stages to the pipeline:
8 
9 1. **Build**: cmake configures the doxygen file - There is a *documentation* build type so that only documentation build dependencies are required. Doxygen then runs to create the documentation.
10 2. **Deploy**: The html pages produced by doxygen are published on *gitlab page*.
11 
12 Runners are set up in the project settings - we currently use shared runners provided by gitlab - make sure they are enabled in the _CI/CD Pipeline_ section of the project settings. **Note** this can mean that there is a wait for resources when the pipeline runs.
13 
14 ## Published documentation
15 
16 The API documentation after publishing is available at this address:
17 
18 [https://ska-tdt.gitlab.io/cheetah](https://ska-tdt.gitlab.io/cheetah)
19 
20 ## Issues
21 
22 It would appear that sometimes the *publish* stage of the pipeline fails, or takes a long time to run - likely because it uses a shared runner, and this may get very overloaded. If this happens it appears that this can prevent further pushes to master branch. In this situation it is best to cancel the job.
23 
24 To do this go to *commits* on the gitlab dashboard - there will be an icon indicating the state of the CI piple (Could be 'fail' or 'running' or 'passed'). Click on this icon to display the jobs. From here it is possible to either 'cancel' and job or re-run it.
25 
26 ## Useful Links
27 
28 [Gitlab Pages Documentation](https://docs.gitlab.com/ce/user/project/pages/index.html)
29 
30 [.gitlab-ci.yml Documentation](https://docs.gitlab.com/ce/ci/yaml/README.html)
31 
32 [Gitlab CI Documentation](https://docs.gitlab.com/ce/ci/README.html)