☰
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.

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:

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:

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:

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

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

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

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

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

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


[^label]: This is the footnote text.
and will be added at the bottom of the page.

  1. This is the footnote text. ↩︎