Authoring documentation

Extensive documentation about reStructuredText and MyST can be found online. Here are some resources to get started:

• reStructuredText Primer from the Sphinx documentation give a good overview of the format.

• reStructuredText User documentation from Docutils offers many links and information about reStructuredText.

• reStructuredText Quick reference from Docutils is a compact reference guide for reStructuredText.

• MyST-NB Documentation is the reference for using MyST-NB.

• MyST Markdown documentation is the reference for MyST Markdown, the language used by MyST-NB.

In the following, important points and guidelines for Finesse will be presented.

reStructuredText (reST)

Sphinx’s default file format is reStructuredText. It is a versatile and extensive language offering many possibilities for creating rich documents with internal and external linking, images, figures, tables and more. To be able to fully utilize the format, some basic concepts need to be understood, notably the concepts of role and directive. They are key mechanisms for adding semantic meaning and extended functionality to documents.

role

A role is an inline markup element used to annotate small pieces of text with specific meaning or behavior. Roles are written using a colon syntax, such as :role:`text` (e.g., :math:`E=mc^2`), and are typically used to insert things like hyperlinks, inline code, or mathematical expressions. Roles help enrich the document by adding metadata or context.

directive

Directives are block-level constructs that extend reST’s capabilities beyond basic text formatting. They begin with a double-dot prefix and include a name and optional arguments or content (e.g., .. note:: or .. code-block:: python). Directives can be used to insert figures, generate tables of contents, or highlight source code.

Markedly Structured Text (MyST)

MyST extends standard Markdown (CommonMark) with features like directives and roles, similar to reStructuredText, making it compatible with Sphinx. MyST-NB allows the MyST language to be used inside Jupyter Notebook markdown cells. This allows authors to easily write Jupyter notebooks to be seamlessly integrated with the rest of the documentation while keeping them executable. See the Comparison between reST and MyST for a short comparison of the notations of reST and MyST.

Comparison between reST and MyST

	reStructuredText	MyST
Role	:role-name:`role content`	{role-name}`role content`
Directives	.. directivename:: arguments :key1: val1 :key2: val2 This is directive content	```{directivename} arguments :key1: val1 :key2: val2 This is directive content ```
Label	.. _my-label:	(my-label)=

Special formatting of the word Finesse

As shown here, Finesse uses a special formatting when displayed. To display it, you need to write |Finesse| when using reStructuredText and as {{Finesse}} when using MyST-NB.

Note

Do not use the special formatting in titles as it can break formatting when linked to or used in a table of contents.

What to add at the top of a page

At the top of a new page, include a label for internal linking and a title. In addition, when writing reStructuredText, you should include the /defs.hrst file so the special formatting of the word Finesse is activated. This formatting is available automatically when using MyST-NB.

Here are simple examples of what a header of a page should look like:

reStructuredText

.. include:: /defs.hrst
.. _my-section:

==================
My awesome section
==================

This amazing section contains ...

MyST-NB

(my-section)=

# My awesome section

This amazing section contains ...

References and links

To link a section, paragraph, figure, etc., a label must be associated with it. The label needs to be set before the corresponding element. Inside a directive, the keyword :name: can be used to create a label.

Setting a label.

	reStructuredText	MyST
Label in text	.. _my-label:	(my-label)=
Label inside directive	:name: my-label	:name: my-label

Linking to internal and external objects

Sphinx enables you to cross-reference modules, classes, functions, and attributes both internal to the project and external to it. To cross-reference an internal object (or attribute, method etc.) simply use the following directives:

• :mod:`.internal_module_name` to create a link to an internal module,

• :class:`.internal_class_name` to create a link to an internal class,

• :func:`.internal_function_name` to create a link to an internal function or :meth:`.internal_class_name.internal_function_name` to create a link to an internal class method,

• :attr:`.internal_class_name.internal_attribute_name` to create a link to an internal class attribute.

The Finesse documentation tooling provides additional cross-reference support for various situations:

• :kat:command:`command_name` to create a link to a kat-script command,

• :kat:element:`element_name` to create a link to a kat-script element,

• :kat:analysis:`analysis_name` to create a link to a kat-script analysis,

• :issue:`123` to create a link to an issue on the tracker,

• :source:`path/to/script.py` to create a link to a source code file relative to the Finesse package root (i.e. /src/finesse/).

Linking to objects in external modules is just as simple. What external modules are available are defined by the intersphinx_mapping inside finesse/docs/source/conf.py. Details on how to specify new targets in this variable see the intersphinx documentation. The available module for interlinking are:

• Python

• Numpy

• Scipy

• Matplotlib

• Networkx

• Pygments

• Pygraphviz

Showing output from inline scripts

With MyST-NB, code execution and output can be used as usual. What you see is what you get.

For reST, the jupyter-sphinx extension is available which provides the ability to execute code embedded in the documentation in a Jupyter kernel, then show the code (with syntax highlighting) alongside the outputs of that code in the documentation. It also supports plot outputs (and others, such as LaTeX and JavaScript widgets).

Code is executed in the environment used to build the documentation, so the finesse package is available to import and run.

Simple code blocks can be executed with .. jupyter-execute:: directives. More advanced usage is possible, such as running scripts within different kernels (using the :id: directive option), showing line numbers, importing and showing the contents of scripts on the file system, etc. See the jupyter-sphinx documentation for more information.

Sections

With MyST-NB, the standard Markdown notation (#, ##, …) need to be used to structure the document.

With reST, there are particular characters assigned to heading levels; the structure is determined from the succession of headings as defined in each .rst file. Finesse documentation should nevertheless ideally follow this convention:

• = with overline, for page titles

• =, for sections

• -, for subsections

• ^, for subsubsections

• ", for paragraphs

Code examples

Write code examples using the same formatting rules as Finesse source code.

Prefer the use of .. code-block:: (provided by Sphinx) rather than .. code:: (provided by docutils).