MKDocs Build¶

Build docs using Python mkdocs.

You need to have:

docs directory at root level.
mkdocs.yml config file.

Inputs¶

INPUT	TYPE	REQUIRED	DEFAULT	DESCRIPTION
doxygen	string	false		Include doxygen output uploaded to `artifact` key.
image	string	false	`"ghcr.io/hotosm/gh-workflows/mkdocs:main"`	Override the image to build mkdocs.
include_artifacts	string	false		Include all uploaded artifacts from the workflow.
keep_extra_files	boolean	false	`false`	Only update modified files. Default false, to clean repo before push.
openapi	string	false		Include openapi output uploaded to `artifact` key.

Outputs¶

No outputs.

Secrets¶

No secrets.

Example Usage¶

Simple publish:

name: Publish Docs

on:
  push:

jobs:
  publish_docs:
    uses: hotosm/gh-workflows/.github/workflows/mkdocs_build.yml@main

Publish with Doxygen & OpenAPI YAML:

name: Publish Docs

on:
  push:
    paths:
      - docs/**
      - src/**
      - mkdocs.yml
    branches: [development]
  # Allow manual trigger (workflow_dispatch)
  workflow_dispatch:

jobs:
  build_doxygen:
    uses: hotosm/gh-workflows/.github/workflows/doxygen_build.yml@main
    with:
      output_path: docs/apidocs

  build_openapi_json:
    uses: hotosm/gh-workflows/.github/workflows/openapi_build.yml@main
    with:
      image: ghcr.io/${{ github.repository }}/backend:ci-${{ github.ref_name }}
      example_env_file_path: ".env.example"
      output_path: docs/openapi.json

  publish_docs:
    uses: hotosm/gh-workflows/.github/workflows/mkdocs_build.yml@main
    needs:
      - build_doxygen
      - build_openapi_json
    with:
      image: ghcr.io/${{ github.repository }}/backend:ci-${{ github.ref_name }}
      doxygen: true
      openapi: true

Last update: July 27, 2024