Tutorial guidelines

Steps in GUI tutorials

For steps in tutorials use the rst-class:: steps.

Example:

.. rst-class:: steps

    | Optionally some context here
    | **1.** The first step, e.g. click on **Edit → Builder**
    | **2.** The second step.

Result:

Optionally some context here

1. The first step, e.g. click on Edit → Builder

2. The second step

GUI icons

In the Tutorials, you can refer to some GUI buttons/icons by using the following substitutions (these substitutions are defined in global_conf.py, but that you have to initialize it in the conf.py of your specific project. See the Tutorials/conf.py).

Icon	Substitution	Name
	|InfoBtn|	More-info button
	|MoreBtn|	Details
	|SCMMenu|	SCM menu
	|Search|	Search box
	|PointerTool|	Pointer tool
	|CTool|	Carbon tool
	|OTool|	Oxygen tool
	|HTool|	Hydrogen tool
	|XTool|	Element tool
	|StructTool|	Structure tool
	|CrystalTool|	Periodic structure tool
	|SymmTool|	Symmetrize tool
	|BondTool|	Bond tool
	|PeriodicViewTool|	Periodic display
	|SliceTool|	Slice tool
	|PreOptimTool|	Pre-optimizer button
	|ADFPanel|	ADF panel
	|ADFviaAMSPanel|	ADF via AMS panel
	|BANDPanel|	BAND panel
	|ConformersPanel|	Conformers panel
	|DFTBPanel|	DFTB panel
	|MMPanel|	MM panel
	|MopacPanel|	Mopac panel
	|QMMMPanel|	QMMM panel
	|QuantumESPRESSOPanel|	Quantum ESPRESSO panel
	|QuildPanel|	Quild panel
	|ReaxFFPanel|	ReaxFF panel
	|ForceFieldPanel|	ForceField panel
	|VASPPanel|	VASP panel
	|AddButton|	Add button
	|DeleteButton|	Delete button

Example:

.. rst-class:: steps

    | In **ADFInput**
    | **1.** Switch to the **BAND panel**: |ADFPanel| **→** |BANDPanel|
    | **2.** In the **search box** |Search| search for ``Diamond`` and select **Crystal → C**

Result:

In ADFInput

1. Switch to the BAND panel: →

2. In the search box search for Diamond and select Crystal → C

Conventions for step descriptions

How to phrase common tasks:

Switch to BAND by clicking on →

In the search box search for Diamond and select Crystal → C

In the panel bar, select Properties → Excitations (UV/Vis), CD

In the menu bar, select View → Reset View

Select Task → Geometry Optimization

In Total charge enter -1

Check/Uncheck the Unrestricted checkbox

Select the Carbon tool and click in the molecule drawing area

Tags

The GUI tutorials use the screx.tags plugin. Set the tags near the top of the .rst file like this:

.. tags:: ADF, Spectroscopy, VCD

They become clickable in the rendered docs to get an overview of all pages with the same tag.

Tags come in three categories:

• engines/programs (red),

• application area (green), and

• other (blue).

The categories and colors are defined in userdoc/Tutorials/screx.toml.

Every tutorial MUST have

• at least one engines/programs tag

• at least one application-area tag

Be liberal when assigning tutorials to application areas so that the corresponding pages look impressive.

Scripting Examples and screx

The preferred way to create new tutorials for PLAMS/Python is through Jupyter notebooks.

These are located in the $AMSHOME/userdoc/PythonExamples directory.

Important

NEVER MODIFY THE EXAMPLE index.rst FILES MANUALLY! They are generated by screx either manually or at build time.

The scripting examples use

• screx.tags to filter on tags, and

• screx.notebooks to combine jupyter notebooks (.ipynb) with some metadata (conf.toml) into rst files read by sphinx. Note that the tags are defined in conf.toml!

screx is both a sphinx plugin and a command-line tool.

Recommendation: Use screx as a command-line tool to manually convert the Jupyter notebooks into .rst. The screx command-line tool has lots of functionality.

git clone [email protected]:hellstrom/screx.git
amspython -m pip install -e screx

Then you can do e.g. amspython -m screx convert my-example. See the screx docs for more detail.

• The screx.toml defines the tag categories

• The (jinja2) templates are in the screx_templates/ directory. These define how to render the data from conf.toml into index.rst. Screx inserts everything from the [page] into the template context, and additionally some extra info (like resolved paths for toc figures). Be careful when editing the preamble.j2 and postamble.j2 templates, since the .rst format is sensitive to newlines and indentation.

• screx_templates/ also has the template_conf.toml file that is the default conf.toml file when running screx new some-new-example.

Older way for legacy PLAMS examples

From these notebooks, documentation pages can be generated by running a script generate_example.sh, located in the examples directory. This will create .rst files which can be included in the PLAMS Examples.

For full instructions on how to do this, see $AMSHOME/scripting/scm/plams/examples/README.md.