How to use FORD for your documentation

Tutorials
2

Thanks for the nice instructions :slightly_smiling_face: Just a few points.

  • When working with a Docker image, I rarely have root permissions, and therefore I need to install pipx using pip.
  • FORD is being developed rather quickly, therefore I think it’s safer to lock its version using Poetry.
  • In Gitlab, I like to have 1 job in the build stage, that allows me to download the artifacts for every merge request. Then, only when the pipeline runs on the main branch I deploy the website.

I copy hereafter the relevant code for the Gitlab CI.

variables:
  PYTHON_VERSION: 3.11
  POETRY_VERSION: 1.8.2

docs:
  stage: build
  image:
    name: python:$PYTHON_VERSION-bullseye
    pull_policy: if-not-present
  script:
    - python -m pip install --user pipx
    - python -m pipx ensurepath
    - source ~/.bashrc
    - pipx install poetry==$POETRY_VERSION
    - poetry install --extras "docs"
    - poetry run ford ford_project.md
  artifacts:
    paths:
      - build_docs
    expire_in: 1h
  interruptible: true
  tags:
    - ubuntu

pages:
  stage: deploy
  image:
    name: alpine:edge
    pull_policy: if-not-present
  needs:
    - docs
  dependencies:
    - docs
  script:
    - mv build_docs public
  artifacts:
    expire_in: 1h
    paths:
      - public
  interruptible: false
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  tags:
    - ubuntu
1 Like