Skip to content

myAPI Documentation

Documentation for myAPI using MkDocs and GitLab Pages.

Initial documentation

Create the initial documentation.

  • Initialize the Python virtual environment if required
uv init --bare .

uv add --dev mkdocs
  • Create a new mkdocs project.
mkdocs new .
  • Update mkdocs.yml 
cat <<EOF > mkdocs.yml
site_name: MyAPI documentation
site_url: https://myapi.scheidegger.io/
site_dir: public
theme:
  name: readthedocs
EOF
  • Update index.md 
cat <<EOF > docs/index.md
# myAPI
EOF

Create Gitlab Pipeline

Create the Gitlab pipeline to build and deploy the documentation to GitLab Pages.

  • Create initial .gitlab-ci.yml
cat <<EOF > .gitlab-ci.yml
variables:
  ALPINE_VERSION: '3.23'
  PYTHON_VERSION: '3.14'
  GITLAB_CI: true
  MKDOCS_BUILD_DIR: "\$CI_PROJECT_DIR/mkdocs/build"
  UV_CACHE_DIR: "\$CI_PROJECT_DIR/.cache/uv"

default:
  image: python:\$PYTHON_VERSION-alpine\$ALPINE_VERSION
  cache:
    paths:
      - \$UV_CACHE_DIR

stages:
  - test
  - build
  - deploy

before_script:
  - pip install mkdocs uv
  - uv sync

api-test-job:
  stage: test
  script:
    - uv sync
    - uv run pytest --cov-report xml:coverage.xml
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml
  coverage: '/(?i)total.*? (100(?:\.0+)?\%|[1-9]?\d(?:\.\d+)?\%)$/'

mkdocs-build-job:
  stage: build
  script:
    - uv run mkdocs build --clean --strict --verbose --site-dir \$MKDOCS_BUILD_DIR
  artifacts:
    paths:
    - \$MKDOCS_BUILD_DIR
    expire_in: 1 week
  rules:
    - changes:
        - docs/**/*
        - mkdocs.yml

mkdocs-deploy-job:
  stage: deploy
  script:
    - uv run mkdocs build --clean --strict --site-dir \$MKDOCS_BUILD_DIR
    - mv \$MKDOCS_BUILD_DIR public
  dependencies:
    - mkdocs-build-job
  pages: true
  only:
    - main

EOF