FORMAL

F(ortran) (f)O(rd) (vitep)R(ess) M(arkdown) (document)A(tion) (htm)L

Generate beautiful API documentation websites for Fortran projects. FORMAL bridges FORD (Fortran Documenter) and VitePress (Vue-powered static site generator) -- it parses your Fortran !< doc comments and produces a complete, searchable, themed documentation site.

Showcases

Projects using FORMAL for their documentation:

ADAM — Accelerated fluid Dynamics on Adaptive Mesh refinement grids | GitHub
BeFoR64 — Base64 encoding/decoding library for Fortran | GitHub
FACE — Fortran ANSI Colors and Escape sequences | GitHub
FiNeR — Fortran INI ParseR and generator | GitHub
FLAP — Fortran command Line Arguments Parser for poor people | GitHub
FUNDAL — Fortran UNified Device Acceleration Library | GitHub
FOSSIL — FOrtran Stereo (si) Litography parser | GitHub
MORTIF — MORTon Indexer (Z-order) Fortran environment | GitHub
MOTIOn — Modular (HPC) Optimized Toolkit (for) IO (in fortra)n | GitHub
PENF — Portability Environment for Fortran poor people | GitHub
StringiFor — Strings Fortran Manipulator with steroids | GitHub
VecFor — Vector algebra class for Fortran poor people | GitHub
VTKFortran — pure Fortran VTK (XML) API | GitHub

Features

Parses Fortran sources using FORD's battle-tested parser
Generates clean Markdown that VitePress renders natively
One page per module with: type components, bound procedures, subroutine/function signatures, argument tables
Auto-generated sidebar grouped by source directory structure
LaTeX math support in doc comments (rendered by MathJax)
Fortran syntax highlighting in code blocks
Scaffolds a ready-to-use VitePress site in seconds
Works with any FORD-compatible Fortran project

See the Documentation Guide.

Author

Stefano Zaghi -- szaghi

Copyrights

This project is distributed under a multi-licensing system:

FOSS projects: GPL v3
Closed source / commercial: BSD 2-Clause, BSD 3-Clause, or MIT

Anyone interested in using, developing, or contributing to this project is welcome — pick the license that best fits your needs.

Installation

From PyPI (recommended)

pipx install formal-ford2vitepress

Or with pip:

pip install formal-ford2vitepress

From source

git clone https://github.com/szaghi/formal.git
cd formal
pipx install -e .

Requirements

Python >= 3.9
FORD >= 7.0 (installed automatically as dependency)
Node.js >= 18 (for VitePress, needed at docs build time only)

Quick start

New project -- scaffold everything

cd /path/to/your/fortran/project
formal init --name "MyProject" --author "Your Name"
cd docs && npm install
formal generate
npm run docs:dev    # opens http://localhost:5173

Existing project -- just generate API docs

# If you already have a FORD project file:
formal generate --project doc/main_page.md --output docs/api

# Or let FORMAL auto-detect:
formal generate

Usage

`formal init`

Scaffolds a VitePress documentation site and creates a FORD project file for your Fortran sources.

formal init [project_root] [options]

| Option | Default | Description | |--------|---------|-------------| | project_root | . | Root of the Fortran project | | --name NAME | Directory name | Project name | | --src-dir DIR [DIR...] | Auto-detect src/ | Source directories | | --exclude-dir DIR [DIR...] | Auto-detect | Directories to exclude | | --docs-dir DIR | docs | Where to create VitePress site | | --ford-file PATH | doc/formal.md | FORD project file location | | --docmark MARK | < | FORD doc comment marker (< = !<) | | --author NAME | | Author name | | --no-math | | Disable LaTeX math support | | --no-fortran-highlight | | Disable Fortran syntax aliases |

What it creates (never overwrites existing files):

your-project/
├── doc/
│   └── formal.md              # FORD project file
└── docs/
    ├── index.md               # Landing page
    ├── package.json           # npm config with scripts
    └── .vitepress/
        └── config.mts         # VitePress config with API sidebar

`formal generate`

Parses Fortran sources and generates VitePress Markdown API documentation.

formal generate [options]

| Option | Default | Description | |--------|---------|-------------| | --project FILE | Auto-detect | FORD project file path | | --output DIR | docs/api | Output directory for generated files | | --src-root PATH | Auto-detect | Root path to strip from source paths | | --quiet | | Suppress progress output |

What it generates:

docs/api/
├── index.md                   # Index page listing all modules
├── _sidebar.json              # Sidebar groups (imported by config.mts)
├── adam_grid_object.md        # One page per Fortran module
├── adam_field_object.md
└── ...

Auto-detection: if --project is not given, FORMAL looks for these files in order:

doc/formal.md
doc/vitepress.md
doc/main_page.md

Writing Fortran doc comments

FORMAL reads FORD-style !< doc comments (configurable via docmark):

module physics_solver
!< Compressible Navier-Stokes solver.
!< Supports 1D, 2D, and 3D configurations.

real(R8P), parameter :: GAMMA = 1.4_R8P !< Ratio of specific heats.

type :: solver_config
   !< Solver configuration.
   integer(I4P) :: order = 5 !< WENO reconstruction order.
   real(R8P)    :: cfl = 0.8 !< CFL number.
   contains
      procedure :: init !< Initialize the solver.
endtype solver_config

contains

subroutine compute_flux(self, q, flux)
!< Compute numerical flux.
!<
!< Uses the Rusanov approximate Riemann solver:
!< $$ F_{i+1/2} = \frac{1}{2}(F_L + F_R) - \frac{\lambda}{2}(U_R - U_L) $$
class(solver_config), intent(in)  :: self    !< Solver config.
real(R8P),            intent(in)  :: q(:)    !< Conservative variables.
real(R8P),            intent(out) :: flux(:) !< Numerical flux.

What gets extracted:

Module-level comments become the module description
Variable comments (same-line !<) become table cell descriptions
Type comments become type section descriptions
Procedure comments become procedure section descriptions with full argument tables
LaTeX math ( $...$ , $$...$$, $...$, \[...\]) renders via MathJax

Generated page structure

Each module page contains (when applicable):

# module_name
> Module description

**Source**: `src/lib/common/module_name.F90`

## Variables
| Name | Type | Attributes | Description |

## Derived Types
### type_name
#### Components
| Name | Type | Attributes | Description |
#### Type-Bound Procedures
| Name | Attributes | Description |

## Interfaces
### interface_name

## Subroutines
### subroutine_name
```fortran
subroutine name(arg1, arg2)

Functions

(same as subroutines, plus return type)


## Integrating with an existing VitePress site

If you already have a VitePress site, add FORMAL's API sidebar to your config:

```typescript
// docs/.vitepress/config.mts
import apiSidebar from '../api/_sidebar.json'

export default defineConfig({
  markdown: {
    math: true,  // if you want LaTeX support
  },
  themeConfig: {
    sidebar: {
      // ... your existing sidebars ...
      '/api/': [
        {
          text: 'API Reference',
          items: [
            { text: 'Overview', link: '/api/' },
          ],
        },
        ...apiSidebar,
      ],
    },
  },
})

Then generate and build:

formal generate --project doc/my_ford_file.md --output docs/api
cd docs && npm run docs:build

Customization

See the Documentation Guide for:

Adding hand-written pages alongside API docs
Customizing sidebar structure and grouping
Modifying the generated Markdown layout
Writing effective Fortran doc comments
LaTeX math and Fortran syntax highlighting
Deployment to GitHub Pages, Netlify, etc.

How it works

Fortran .F90 sources
    │
    │  FORD parser (load_settings + Project + correlate)
    │  extracts modules, types, procedures, doc_list
    ▼
FORD Project object model
    │
    │  FORMAL generator (format_module, format_type, ...)
    │  walks the object tree, generates Markdown
    ▼
docs/api/*.md + _sidebar.json
    │
    │  VitePress (npm run docs:build)
    ▼
Static HTML

Formal

Install / Use

README