Navigation :

How to write pages

About this web page

The Octopus documentation web pages are written in markdown and use Hugo as framework with the hugo-theme-docdock theme. Hugo is a static webpage generator, which builds web pages from markdown sources.

For the Octopus pages, we keep these markdown sources within the Octopus source repository, which should encourage to write documentation whenever new code is added, and to update the documentation in case of code changes. The remaining files (e.g. configuration, shortcodes) required for the Hugo system reside in a separate repository.

The header

Hugo requires a header on each page, which contains metadata about the page. Let’s have a look at this example:


---
title: "Getting started"
description: "Learn how to run the code"
weight: 1
tutorials: ["Octopus Basics"]
theories: ["DFT"]
calculation_modes: ["Ground state"]
system_types: ["Molecule"]
species_types: ["Pseudopotentials"]
features: ["Total energy"]
utilities: []
difficulties: ["basic"]
---

The minimum required header must contain:


---
title: "Getting started"
---

Without these lines, a page will not be rendered to HTML. The description should be a one-line summary of the page, and weight determines the order, in which pages are displayed in listings, with smaller number being displayed first.

The remaining entries are part of the so-called taxonomy, and are used to assign pages to certain categories. See Tutorials as example.

Hugo shortcodes

Hugo provides so-called shortcodes, which allow to define functions or macros, which can be used on a markdown page.

{{< octopus >}}: Octopus
{{< octopus-version >}}: 11
{{< emph "text" >}}: text
{{< code "text" >}}: text
{{< code-line "text" >}}: text
{{< file "text" >}}: text
{{< command "text" >}}: text
{{< command-line "text" >}}:
text
{{< name "text" >}}: text

Some of these seem redundant, but they originate from porting the old wikimedia pages to the new framework. Shortcodes as those above receive any content as argument. This, however, does not allow to render further markup or other shortcodes inside this content. If this is required, one has to use shortcodes which come as a opening and closing shortcode. Some examples for these are:

Code blocks:
{{< code-block >}}
Example:
{{< octopus >}} {{< octopus-version >}}
{{< /code-block >}}

which will display as:
```
Example:
Octopus  11
```
Inline code:
An inline code segment like {{< code-inline >}}This is version {{< octopus-version >}}{{< /code-inline >}} will display the text This is version 11 inline with the paragraph.

Other usful shortcodes:

Units

Compilation

Automatically generated pages

The information about the variables is automatically generated from the source code.

Versioning of the documentation

The Hugo system, together with the scripts to build the pages, can provide the documentation for different (major) versions of Octopus.

If, for a given branch of the code, the documentation is contained in the folder <basedir>/doc/hugo/ , the contents of these folders will be copied into the Hugo content/ folder, before the pages for that version are created. If this directory does not exist, the files will be taken from default_content/ within the octopus documentation repository.

Version dependent content

In general, content which is only for given versions of Octopus should be organized through including the documentation in the Octopus repository. In case, version dependent content has to be added for older branches, which do not have the documentation in the code repository, there are the shortcodes:

{{< min-version "version number" >}} Content {{< /min-version >}}
{{< max-version "version number" >}} Content {{< /max-version >}}

Referencing other parts of the documentation

In order to create links to sections of the manual or tutorial, which refer to the correct Octopus version, the following shortcodes are provided:

{{< manual "Section:Name" "display text" >}}: create a link to a manual page
{{< tutorial "Section:Name" "display text" >}}: create a link to a tutorial page
{{< developers "Section:Name" "display text" >}}: create a link to a developers page
{{< variable "VariableName" >}}: create a link to a variable reference
{{< versioned-link "page address" "display text" >}}: create a link to a page, where the address is relative to the top page of a given version.

Including input files

Due to some limitations of Hugo, we cannot use shortcodes to include input files into a markdown file. Instead, this is handled by a shell script ( build-pages.sh), which preprocesses markdown files, and inserts annotated input file. In a markdown file we can use

 
    #include_input filename

where filename includes the path, relative to the Octopus <basedir>. This command copies the file from the Octopus source tree into the hugo folders, and also annotates the file, i.e. is replaces all occurances of known variable names by the {{< variable "VariableName" >}}, which produces a link to the corresponding variable reference.


{{< code-block >}}
#include_input filename
{{< /code-block >}}

Example

The following markdown excerpt


{{< expand "click to expand 'testsuite/tutorials/01-octopus_basics-getting_started.01-H_atom.inp'" >}}
{{< code-block >}}
#include_input "testsuite/tutorials/01-octopus_basics-getting_started.01-H_atom.inp"
{{< /code-block >}}
{{< /expand >}}

will generate the following result:

click to expand 'testsuite/tutorials/01-octopus_basics-getting_started.01-H_atom.inp'


CalculationMode = gs

%Coordinates
 'H' | 0 | 0 | 0
%

### Including input file snippets In addition to complete input files, it is also possible to include a section, or snippet, of an input file. The syntax is similar to the above, but uses the macro {<

>}, as demonstrated in the following example:


{{< expand "click to expand 'octopus/testsuite/tutorials/01-octopus_basics-getting_started.01-H_atom.inp'" >}}
{{< code-block >}}
#include_input testsuite/tutorials/01-octopus_basics-getting_started.01-H_atom.inp calc_mode
{{< /code-block >}}
{{< /expand >}}


This requires the markers "#snippet_startname" and "#snippet_endname" 
in the input file. Due to the leading '#'. Octopus treats them as comments and ignores those markers.



    
        
        
        
        
        Example
        
        
    
    


The following markdown excerpt


{{< code-block >}}
#include_input_snippet testsuite/tutorials/01-octopus_basics-getting_started.01-H_atom.inp calc_mode
{{< /code-block >}}


will generate the following result:

 




    



Including type definitions
Similar to the above macros to include some testfiles, there is also a macro to include the definition block of some user defined types.
Using

#include_type_def <typename>

extracts the corresponding source lines from the correct version of the code and inserts them into the markdown file, before further processing.


Note that no comments after the type name are allowed in the Fortran source. Otherwise the extraction preprocessor does not recognise the line.


To also use the Fortran source highlighting of Hugo it is best to sandwich that by

```Fortran
```



    
        
        
        
        
        Example
        
        
    
    


The following markdown excerpt


{{% expand "click to expand the definition of batch_t" %}}
```Fortran
#include_type_def batch_t
```
{{% /expand %}}


will generate the following result:



 


    
        
        
        
        
        click to expand the definition of batch_t
        
        
    
    
  type batch_t
    private
    integer,                        public :: nst
    integer,                        public :: dim
    integer                                :: np

    integer                                :: ndims
    integer,           allocatable         :: ist_idim_index(:, :)
    integer,           allocatable, public :: ist(:)

    logical                                :: is_allocated
    logical                                :: own_memory !< does the batch own the memory or is it foreign memory?
    !> We also need a linear array with the states in order to calculate derivatives, etc.
    integer,                        public :: nst_linear

    integer                                :: status_of
    integer                                :: status_host
    type(type_t)                           :: type_of !< either TYPE_FLOAT or TYPE_COMPLEX
    integer                                :: device_buffer_count !< whether there is a copy in the opencl buffer
    integer                                :: host_buffer_count !< whether the batch was packed on the cpu
    logical                                :: special_memory
    logical                                :: needs_finish_unpack


    !> unpacked variables; linear variables are pointers with different shapes
    FLOAT, pointer, contiguous,     public :: dff(:, :, :)
    CMPLX, pointer, contiguous,     public :: zff(:, :, :)
    FLOAT, pointer, contiguous,     public :: dff_linear(:, :)
    CMPLX, pointer, contiguous,     public :: zff_linear(:, :)
    !> packed variables; only rank-2 arrays due to padding to powers of 2
    FLOAT, pointer, contiguous,     public :: dff_pack(:, :)
    CMPLX, pointer, contiguous,     public :: zff_pack(:, :)

    integer,                        public :: pack_size(1:2)
    integer,                        public :: pack_size_real(1:2)

    type(accel_mem_t),              public :: ff_device

  contains
    procedure :: check_compatibility_with => batch_check_compatibility_with
    procedure :: clone_to => batch_clone_to
    procedure :: clone_to_array => batch_clone_to_array
    procedure :: copy_to => batch_copy_to
    procedure :: copy_data_to => batch_copy_data_to
    procedure :: do_pack => batch_do_pack
    procedure :: do_unpack => batch_do_unpack
    procedure :: finish_unpack => batch_finish_unpack
    procedure :: end => batch_end
    procedure :: inv_index => batch_inv_index
    procedure :: is_packed => batch_is_packed
    procedure :: ist_idim_to_linear => batch_ist_idim_to_linear
    procedure :: linear_to_idim => batch_linear_to_idim
    procedure :: linear_to_ist => batch_linear_to_ist
    procedure :: pack_total_size => batch_pack_total_size
    procedure :: remote_access_start => batch_remote_access_start
    procedure :: remote_access_stop => batch_remote_access_stop
    procedure :: status => batch_status
    procedure :: type => batch_type
    procedure :: type_as_int => batch_type_as_integer
    procedure, private :: dallocate_unpacked_host => dbatch_allocate_unpacked_host
    procedure, private :: zallocate_unpacked_host => zbatch_allocate_unpacked_host
    procedure, private :: allocate_unpacked_host => batch_allocate_unpacked_host
    procedure, private :: dallocate_packed_host => dbatch_allocate_packed_host
    procedure, private :: zallocate_packed_host => zbatch_allocate_packed_host
    procedure, private :: allocate_packed_host => batch_allocate_packed_host
    procedure, private :: allocate_packed_device => batch_allocate_packed_device
    procedure, private :: deallocate_unpacked_host => batch_deallocate_unpacked_host
    procedure, private :: deallocate_packed_host => batch_deallocate_packed_host
    procedure, private :: deallocate_packed_device => batch_deallocate_packed_device
  end type batch_t

    





Note that the

```Fortran
```

construction only works if the expand is given in the form {{% expand ... %}} ... {{% /expand %}}. The
variant {{< expand ... >}} ... {{< /expand >}} does not work.




    

Including code snippets
Finally, there is a macro to include a general code snipped, which has to be marked in the source code as follows:
...
!# doc_start <name>
some code ...
!# doc_end
Using

```Fortran
#include_code_doc <name>
```

extracts the corresponding source lines from the correct version of the code and inserts them into the markdown file, before further processing.
Including mathematical formulas
The Hugo framework to generate the pages is set up to use katex to render mathematical formulas. The headers, which are silently included
in every page contain scripts, which enable the rendering of formulas, typeset in LaTeX. Further information about katex can be found here.
In short, most LaTeX formulas can be inserted, either inline, enclosed by single ‘$’ characters, or as separate lines, using double ‘$$’s.


    
        
        
        
        
        Examples
        
        
    
    
The density is defined by $n({\bf r}) = \sum_i |\varphi_i({\bf r})|^2$, where the wavefunctions obey
$$
\left( -\frac{\nabla^2}{2 m} + v({\bf r}) \right) \varphi_i({\bf r}) = \epsilon_i \varphi_i({\bf r}) .
$$
The density is defined by $n({\bf r}) = \sum_i |\varphi_i({\bf r})|^2$, where the wavefunctions obey
$$
\left( -\frac{\nabla^2}{2 m} + v({\bf r}) \right) \varphi_i({\bf r}) = \epsilon_i \varphi_i({\bf r}) .
$$

    


In some cases, the equations do not render correctly. In this cases, it might be necessary to escape some control characters  (mainly the underscore) by an extra backslash.
For further details, see e.g. this web page


References
Two shortcodes for references are available.

{{< article title="title" authors="authors" journal="journal" volume="volume" pages="pages" year="year" doi="doi" >}}
{{< book    title="title" authors="authors" publisher="publisher" year="year" pages="pages" isbn="isbn" >}}



    
        
        
        
        
        Examples
        
        
    
    


authors, title,  journal volume pages (year); 
 

title , publisher  pages, year; isbn=isbn

    

Footnotes can be created by adding [^label] in the text¹. The footnote content is then added as:

[^label]: This is the footnote text.

and will be added at the bottom of the page.




This is the footnote text. ↩︎