Navigation :

Variable desription

The reference section of the Octopus input variables is automatically generated from the source code.

Source documentation

The syntax for the annotation in the source code can be seen in the following example.

    !%Variable PropagationSpectrumTransform
    !%Type integer
    !%Default sine
    !%Section Utilities::oct-propagation_spectrum
    !%Description
    !% Decides which transform to perform, if <tt>SpectrumMethod = fourier</tt>.
    !%Option sine 2
    !% Sine transform: <math>\int dt \sin(wt) f(t)</math>. Produces the imaginary part of the polarizability.
    !%Option cosine 3
    !% Cosine transform: <math>\int dt \cos(wt) f(t)</math>. Produces the real part of the polarizability.
    !%Option laplace 1
    !% Real exponential transform: <math>\int dt e^{-wt} f(t)</math>. Produces the real part of the polarizability at imaginary
    !% frequencies, <i>e.g.</i> for Van der Waals <math>C_6</math> coefficients.
    !% This is the only allowed choice for complex scaling.
    !%End
    call parse_variable(namespace, 'PropagationSpectrumTransform', SPECTRUM_TRANSFORM_SIN, spectrum%transform)
    if(.not.varinfo_valid_option('PropagationSpectrumTransform', spectrum%transform)) then
      call messages_input_error(namespace, 'PropagationSpectrumTransform')
    end if
    call messages_print_var_option(stdout, 'PropagationSpectrumTransform', spectrum%transform)

This description will be used by the oct-help command, and also for the documentation web pages.

Note that LaTeX commands can be used in the description text. See here for details.

Using the python scripts

When building the documentation, a set of python scripts are parsing the source code, as well as the input files of the testsuite and the markdown files of the manual and the tutorials to generate a compresensive database of the variables, inlcuding references to the source, testfiles and the tutorials, which is written to the varinfo.json file.

JSON entry for this example

This JSON file is then used to generate the input variable web pages. The information is also used by the script annotate_input.py , which is automatically invoked by the #include_input directive, but can also be called manually, if a part of an input file should be included in some tutorial markdown file.

Automatic generation of links

The script, which parses the source files, also parses the testsuite input files and the tutorial files. These, together with a link to the source file in which the variable is parsed, are them added to the variable description pages.