FORMAL

Appearance

FORMALFortran API Documentation

Generate beautiful documentation websites for Fortran projects using FORD + VitePress.

Guide
View on GitHub

FORD-Powered Parsing

Parses Fortran sources using FORD's battle-tested parser. Works with any FORD-compatible project.

VitePress Rendering

Generates clean Markdown that VitePress renders natively into a modern, searchable, themed site.

One Page Per Module

Type components, bound procedures, subroutine/function signatures, and argument tables -- all auto-generated.

Auto-Generated Sidebar

Sidebar groups are derived from your source directory structure and update automatically on each run.

LaTeX Math Support

Write equations in doc comments using $...$ or $$...$$ -- rendered by MathJax.

Scaffold in Seconds

Run `formal init` to scaffold a ready-to-use VitePress site with FORD project file.

Showcases ​

Projects using FORMAL for their API documentation:

  • BeFoR64 — Base64 encoding/decoding library for Fortran  |  GitHub
  • FACE — Fortran ANSI Colors and Escape sequences  |  GitHub
  • FLAP — Fortran command Line Arguments Parser for poor people  |  GitHub
  • PENF — Portability Environment for Fortran poor people  |  GitHub
  • StringiFor — Strings Fortran Manipulator with steroids  |  GitHub

Author ​

Stefano Zaghi -- szaghi

Copyrights ​

This project is distributed under a multi-licensing system:

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

Installation ​

bash
pipx install formal-ford2vitepress

Or with pip:

bash
pip install formal-ford2vitepress

From source ​

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

Requirements ​

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

Quick Start ​

New project -- scaffold everything ​

bash
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 ​

bash
# 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.

formal init [project_root] [options]
OptionDefaultDescription
project_root.Root of the Fortran project
--name NAMEDirectory nameProject name
--src-dir DIR [DIR...]Auto-detect src/Source directories
--exclude-dir DIR [DIR...]Auto-detectDirectories to exclude
--docs-dir DIRdocsWhere to create VitePress site
--ford-file PATHdoc/formal.mdFORD project file location
--docmark MARK<FORD doc comment marker (< = !<)
--author NAMEAuthor name
--no-mathDisable LaTeX math support
--no-fortran-highlightDisable Fortran syntax aliases

formal generate ​

Parses Fortran sources and generates VitePress Markdown API documentation.

formal generate [options]
OptionDefaultDescription
--project FILEAuto-detectFORD project file path
--output DIRdocs/apiOutput directory for generated files
--src-root PATHAuto-detectRoot path to strip from source paths
--quietSuppress progress output

How It Works ​

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

FORD's pipeline goes parse -> correlate -> markdown -> HTML. FORMAL hooks in after correlate() and reads the raw doc_list (Markdown strings) from every entity, skipping FORD's own HTML generation entirely. VitePress handles the Markdown-to-HTML conversion with its own theme.