Skip to content

Commit 32fbffb

Browse files
yoricklassmannyoricklassmann
authored
First steps towards a useful developer documentation (#42)
* Added FORD project file * Made some minor modifications to the TrajectoryModule docs to show how to make things look nicer in FORD. * Added docs build to lint.yml workflow * Removed trailing whitespace * Split docs-build to a separate job + added upload-artifact action * Implement requested changes * Forgot to modify CI job. * Implement final requested changes. * Does this work?
1 parent fa45668 commit 32fbffb

5 files changed

Lines changed: 98 additions & 40 deletions

File tree

‎.github/workflows/lint.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,21 @@ jobs:
2727

2828
- name: Run prek hooks
2929
run: prek run --all-files --show-diff-on-failure --color always
30+
31+
dev-docs-build:
32+
runs-on: ubuntu-24.04
33+
timeout-minutes: 10
34+
35+
steps:
36+
- uses: actions/checkout@v6
37+
38+
- name: Install FORD
39+
run: pip install ford
40+
41+
- name: Build docs
42+
run: ford ford_config.md
43+
44+
- uses: actions/upload-artifact@v7
45+
with:
46+
name: Docs artifact
47+
path: ./developer_docs/

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,3 +42,6 @@ src/moddepend
4242
src/build_info.F90
4343
# from fprettify
4444
__pycache__/
45+
46+
# FORD dev docs
47+
./developer_docs

‎CONTRIBUTING.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,3 +97,12 @@ git config blame.ignoreRevsFile .git-blame-ignore-revs
9797
```
9898

9999
This is done automatically in GitHub UI.
100+
101+
## Building the developer documentation
102+
103+
Building the docs is straightforward:
104+
105+
1. [Install FORD with your favorite python package manager](https://forddocs.readthedocs.io/en/stable/index.html#sec-installation)
106+
2. Execute `ford ford_config.md`
107+
108+
That's it.

‎ford_config.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
project: OpenFMS
3+
preprocessor: gfortran -E
4+
display: public
5+
protected
6+
output_dir: ./developer_docs
7+
---
8+
9+
Auto-generated developer documentation for OpenFMS

‎src/modules/TrajectoryModule.f90‎

Lines changed: 59 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,28 @@
1-
! Copyright Todd J. Martinez and Raphael D. Levine, 1994
1+
!---------------------------------------------------------------------!
2+
! !
3+
! Copyright Todd J. Martinez and Raphael D. Levine, 1994 !
4+
! !
5+
!---------------------------------------------------------------------!
6+
!>
7+
!> @brief Trajectory class specification and related methods
8+
!>
9+
!> This module specifies the trajectory type, and all related
10+
!> methods. A given instance of a trajectory object contains the
11+
!> classical position and momenta for a given trajectory basis function
12+
!> at a given instant in time. Also included in the trajectory data
13+
!> structure are electronic structure quantities, in the "T_ElecStruc"
14+
!> datatype, and flags describing those quantities in "T_ESFlags".
15+
!>
16+
!> This module also defines several other derived types, some of which
17+
!> are stored in T_Trajectory: T_ElecStruc, T_ESFlags, T_BFlags
18+
!>
19+
!> Methods in this module pertain to basic manipulation of T_Trajectory
20+
!> derived type. Methods that pertain to electronic structure are
21+
!> in the TrajectoryCalcsModule, while the methods related to file IO
22+
!> are in TrajectoryIOModule.
23+
!>
24+
!> \image latex "../sources/TrajModule.png"
225
!>
3-
!! @brief Trajectory class specification and related methods
4-
!!
5-
!! This module specifies the trajectory type, and all related
6-
!! methods. A given instance of a trajectory object contains the
7-
!! classical position and momenta for a given trajectory basis function
8-
!! at a given instant in time. Also included in the trajectory data
9-
!! structure are electronic structure quantities, in the "T_ElecStruc"
10-
!! datatype, and flags describing those quantities in "T_ESFlags".
11-
!!
12-
!! This module also defines several other derived types, some of which
13-
!! are stored in T_Trajectory: T_ElecStruc, T_ESFlags, T_BFlags
14-
!!
15-
!! Methods in this module pertain to basic manipulation of T_Trajectory
16-
!! derived type. Methods that pertain to electronic structure are
17-
!! in the TrajectoryCalcsModule, while the methods related to file IO
18-
!! are in TrajectoryIOModule.
19-
!!
20-
!! \image latex "../sources/TrajModule.png"
21-
!<
2226
module TrajectoryModule
2327

2428
use GlobalModule, only: D2, Pi, DefInt, DefReal, DefComp, fmiOut, FPZero, &
@@ -37,39 +41,54 @@ module TrajectoryModule
3741
!--------------------------------------------------------------------!
3842

3943
!--------------------------------------------------------------------!
40-
! Flags to track electronic structure status
44+
45+
!> Flags to track electronic structure status
4146
type T_ESFlags
42-
! private
43-
logical :: zIgnoreErrors, & !< For the first timestep of centroids only - we can ignore phasing and diabatization errors.
44-
zESExists, & !< Does a wavefunction exist to restart from?
45-
ZPotEnCurrent, & !< Is the potential calculated for the current geometry
46-
ZTransDipsCurrent, & !< If transition dipoles are calculated for this geometry
47-
ZTransDipsCurrentxf, & !< xf added
48-
ZDipolesCurrent, & !< If dipoles are calculated for this geometry
49-
ZQuadpolesCurrent, & !< If quadrupoles are calculated for this geometry
50-
zMMPotCurrent, & !< If MM potential is calculated for the current geometry
51-
zMMForceCurrent, & !< If MM forces are calculated for the current geometry
52-
zModPotCurrent !< Are external force modifications current?
5347

48+
!> For the first timestep of centroids only - we can ignore
49+
!> phasing and diabatization errors.
50+
logical :: zIgnoreErrors
51+
!> Does a wavefunction exist to restart from?
52+
logical :: zESExists
53+
!> Is the potential calculated for the current geometry
54+
logical :: ZPotEnCurrent
55+
!> If transition dipoles are calculated for this geometry
56+
logical :: ZTransDipsCurrent
57+
!> xf added (TODO: Needs more thorough documentation!)
58+
logical :: ZTransDipsCurrentxf
59+
!> If dipoles are calculated for this geometry
60+
logical :: ZDipolesCurrent
61+
!> If quadrupoles are calculated for this geometry
62+
logical :: ZQuadpolesCurrent
63+
!> If MM potential is calculated for the current geometry
64+
logical :: zMMPotCurrent
65+
!> If MM forces are calculated for the current geometry
66+
logical :: zMMForceCurrent
67+
!> Are external force modifications current?
68+
logical :: zModPotCurrent
69+
70+
! TODO: Add appropriate documentation here! Also the name
71+
! DerivCurrent is rather misleding, as it contains information
72+
! on if the forces/couplings are up-to-date. Maybe splitting it
73+
! up into two flags?
5474
!< Is the coupling current with the geometry for this state?
5575
!< Are the derivatives current with the geometry for this state?
5676
logical, allocatable :: ZDerivCurrent(:, :)
5777
logical, allocatable :: ZSOMCurrent(:, :, :, :)
5878
!< This should be replaced by zForcesCurrent
79+
5980
end type T_ESFlags
6081

61-
!---------------------------------------------------------------------!
62-
!>
63-
!! Flags to track bundle status
64-
!<
82+
!> Flags to track bundle status
6583
type T_BFlags
66-
! private
67-
logical :: zBundleCurrent, & !< Has the trajectory changed since the last bundle calculation?
68-
ZAmpDotCurrent !< Is AmpDot current?
84+
85+
!> Has the trajectory changed since the last bundle calculation?
86+
logical :: zBundleCurrent
87+
!> Is AmpDot current?
88+
logical :: ZAmpDotCurrent
6989

7090
end type T_BFlags
7191

72-
!----------------------------------------------------------------------------
7392
!>
7493
!! Electronic structure data for a trajectory
7594
!! TODO: Should this type live in ElecStrucModule?

0 commit comments

Comments
 (0)