Docdeployer

Deploy any documentation to CodeFirst static pages.

You can use your favorite documentation generator, and specify the output directory to be deployed.

Examples

• Doxygen
• JavaDoc
• Swagger
• mdBook
• Docusaurus

The generic way to use this image is to generate the documentation in a separate pipeline step. It can use any image, as long as the generated documentation is shared with the docdeployer step. With Drone, the /drone/src directory is automatically shared.

Doxygen

A Docker image is used to call Doxygen in the right directory, here code. The generated HTML output is then deployed to the docs directory on CodeFirst.

kind: pipeline
name: default

steps:
  - name: build-docs
    image: corentinaltepe/doxygen:latest
    commands:
      - cd code
# Uncomment to generate a Doxyfile in the pipeline if not committed in the repository.
#      - doxygen -s -g && sed -i 's/RECURSIVE              = NO/RECURSIVE              = YES/' Doxyfile
      - doxygen

  - name: deploy-docs
    image: hub.codefirst.iut.uca.fr/maxime.batista/codefirst-docdeployer:0.2
    settings:
      source: ./code/html
      target: docs
    failure: ignore
    depends_on: [build-docs]
    when:
      branch:
        - master
        - main

Swagger

Here, the OpenAPI definition file is supposed to be generated by a previous step at target/openapi.yaml or committed to the repository, and is deployed to the api-docs directory on CodeFirst. A transform step is performed to generate the UI.

kind: pipeline
name: default

steps:
  - name: deploy-swagger
    image: hub.codefirst.iut.uca.fr/maxime.batista/codefirst-docdeployer:0.2
    settings:
      source: ./target/openapi.yaml
      target: api-docs
      transform: swagger
    failure: ignore
# You may depend on a previous step that generate the OpenAPI definition file
#    depends_on: [build-openapi]
    when:
      branch:
        - master
        - main

JavaDoc

The Maven JavaDoc plugin is used to generate the documentation at the root of the repository. It is then deployed to the javadoc directory on CodeFirst by using the standard target/site/apidocs directory.

kind: pipeline
name: default

steps:
  - name: build-javadoc
    image: maven:3-eclipse-temurin-17-alpine
    commands:
      - mvn javadoc:javadoc

  - name: deploy-javadoc
    image: hub.codefirst.iut.uca.fr/maxime.batista/codefirst-docdeployer:0.2
    settings:
      source: ./target/site/apidocs
      target: javadoc
    failure: ignore
    depends_on: [build-javadoc]
    when:
      branch:
        - master
        - main

mdBook

The book in the book directory is generated in the build directory, and then deployed to the book directory on CodeFirst.

kind: pipeline
name: default

steps:
  - name: build-book
    image: ghcr.io/peaceiris/mdbook:v0.4.34
    commands:
      - mdbook build book -d build

  - name: deploy-book
    image: hub.codefirst.iut.uca.fr/maxime.batista/codefirst-docdeployer:0.2
    settings:
      source: book/build
      target: book
    failure: ignore
    depends_on: [build-book]
    when:
      branch:
        - master
        - main

Docusaurus

The website is stored in the site directory. The NPM dependencies are installed, and the website is built in the site/build directory. The generated website is deployed to the docusaurus directory on CodeFirst.

kind: pipeline
name: default

steps:
  - name: build-site
    image: node:20-alpine3.18
    commands:
      - cd site
      - yarn install --frozen-lockfile
      - yarn build

  - name: deploy-site
    image: hub.codefirst.iut.uca.fr/maxime.batista/codefirst-docdeployer:0.2
    settings:
      source: site/build
      target: docusaurus
    failure: ignore
    depends_on: [build-site]
    when:
      branch:
        - master
        - main

Configuration

This image is designed to be used a Drone plugin. It can be configured using the following parameters:

Parameter	Description
source	The directory* containing the files to deploy.
target	The target directory to deploy the documentation to.
transform	The transformation to apply to the documentation. Can be none (default), swagger.

*If using the swagger transformation, the source parameter must be the path to the OpenAPI definition file.