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.

16 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
2 Likes
New Release of Forgex - Fortran Regular Expression v3.4
Resources for creating a blog/website for a Fortran learning journey
3

Installing FORD 7.0.12 in Fedora Linux 43:

$ sudo dnf install pip
$ pip install ford
$ sudo dnf install graphviz

In fact, when installing FORD, pip is also installing graphviz-0.20.3, but when launching FORD, I obtain a warning for an unknown reason: Warning: Will not be able to generate graphs. Graphviz not installed. That’s why I have finally installed graphviz-0:13.1.2-3 using the Fedora package.

4

Installing FORD 7.0.12 in Debian Forky/Sid:

$ sudo apt install ford

:slight_smile:

2 Likes
5

Debian Sid seems to be the only Linux distribution offering natively FORD:
https://pkgs.org/download/ford

6

A complementary visit on repology.org

Packaging status

indeed acknowledges @amckinstry as the volunteering uploader of ford to Debian .and. its relatives.

2 Likes
7

Thanks for this!

1 Like
8

Note that since FORD 7.0.0, you can put the FORD options directly in your fpm.toml manifest, instead of the ford.yml file:

v7.0.0
This is a major release that changes quite a few thing. Notably, we have updated the CSS framework, Bootstrap, to 5.3, which changes the look of built websites a bit. We’ve also added processing of namelists, and the ability to set project options in fpm.toml files.

The options must be put in an extra.ford section, with the following syntax:

[extra.ford]
project             = "ForColormap"
year                = "2023-2026"
summary             = '<img src="media/logo_forcolormap-roma_8.svg" alt="Logo" width="300" /><br> A Fortran library for scientific colormaps'
project_github      = "https://github.com/vmagnin/forcolormap"
...
search              = true
print_creation_date = true
sort                = "permission-alpha"
display             = ["public", "private", "protected"]

For more information, see:

3 Likes
9

Thanks @nbehrnd, I didn’t know Ford was packaged in all these repos, so I’ve put this badge in the README :slight_smile:

1 Like