Requirements

• standalone tool that can be run to automatically process the fortran source files and generate a set of static html pages or hyper-linked pdf (latex).
• Each module would have a page listing declared derived types, functions, and dependencies (use statements).
• Each function would have a section on the module page that had a general comment/notes about the function, list of links to dependencies (derived types, functions/subroutine calls, use statements).
• The markup in the source code should be minimal. This will require all source code to stick to some standard conventions:
  • Immediately following the function/subroutine statement there can be a comment describing the purpose of the function, and any notes about it's use, assumptions, etc.
  • The use statements will be be recorded as dependencies.
  • implicit none will be added before variable declarations.
  • variable declarations will use the "::" notation so they can be easily identified by the parser.
  • The function parameters will be recorded and noted with the variable declarations.
  • Any call statements in the body of the function will be recorded as dependencies and linked to the appropriate function in the doc.
  • Note, identifying function calls, e.g. ReactionCreate() below, will require a two pass approach to scanning the source. One pass to generate a list of known function names, a second to search for those names in the bodies of functions.
  • Example:

! ************************************************************************** !

subroutine ReactionInit(reaction,input,option)
  !
  ! Initializes the reaction object, creating object and
  ! reading first pass of CHEMISTRY input file block.
  !

  use Option_module
  use Input_Aux_module
  use Reaction_Sandbox_module, only : RSandboxInit

  implicit none

  type(reaction_type), pointer :: reaction
  type(input_type) :: input
  type(option_type) :: option

  reaction => ReactionCreate()

  ! must be called prior to the first pass
  call RSandboxInit(option)

  call ReactionReadPass1(reaction,input,option)
  reaction%primary_species_names => GetPrimarySpeciesNames(reaction)
  ! PCL add in colloid dofs
  option%ntrandof = GetPrimarySpeciesCount(reaction)
  option%ntrandof = option%ntrandof + GetColloidCount(reaction)
  option%ntrandof = option%ntrandof + GetImmobileCount(reaction)
  reaction%ncomp = option%ntrandof

end subroutine ReactionInit

Implementation

• Language: * perl - probably require less code because of better language support for text manipulation. * python - already use python for various tools with pflotran, easier for people to understand and modify. Can easily dump info into a pickle/database for reuse. use template systems like jinja2 to generate html or latex.