How to use FORD for your documentation

Tutorials
1

I think it would be interesting to have a thread where people share their knowledge about using FORD. Until now, I had two projects with a FORD documentation but the main steps were carried out by collaborators. After studying it, I have now succeeded in creating FORD documentations in two other projects, following those steps:

  • Creating a ford.yml project file at the root of the project. The easiest way is to copy a file from another project, study it with the official doc, and make changes according to your needs.

  • The following step is facultative if your objective is to generate your doc using a GitHub workflow, but installing FORD locally can be useful for testing. I have used pipx in Ubuntu 24.04:

    • $ sudo apt install pipx
    • $ pipx install ford
    • $ pipx install pcpp
    • Generating your doc directory is as simple as $ ford ford.yml

  • You can create a file ./github/workflows/ford.yml. Once again, the easiest way is to copy a file from another project, study it with the official doc, and make changes according to your needs.

  • Commit and push the two files.

    • Wait for the end of the workflow. A gh-pages branch has been created by the workflow.

  • In your GitHub page, go in Settings > Pages

    • Choose the branch gh-pages and save.

  • In the settings of the “About” box of your GitHub project, check the box “Use your GitHub Pages website” to make the .github.io/ link appear.

  • You can now add FORD comments into your Fortran code, using !! (following the Fortran code) or !> (preceding your code). Commit and push…

The whole process is neither complicated nor simple. But once you know what to do, it can be done in 10 minutes.

As a beginner concerning FORD and workflows, I hope to learn more with your comments.

13 Likes
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