The CGNS community can help you to understand, use and even participate to the CGNS standard. There are various means. As a user of the CGNS files and tools, you can ask questions to the CGNS Discussion Forum or browse the web resources. If you are a developer and you want to install the libs, the docs or the tools you jump to Development support.

Discussion Forum

The discussion forum is available on You must have an account. Notifications of new posts are controlled by setting the proper watch notifications for the CGNS/CGNS repository.

Prior to 2020, there was a CGNSTalk mailing list (connected to NASA) that has since been discontinued. The CGNSTalk mailing list archives [GZIPPED TXT FILE] are available from 2000 to 2020.

Web resources

None listed yet.

Development support

Building libraries and tools

The CGNS libs and tools are hosted on Github; the associated documentation can be found on this page.

Building the documentation

The documentation is generated from text files. We use Sphinx to produce the web pages from these text files and a set of layout templates. The template we use for CGNS is a modified version of the Guzzle template. This modified version is released with the doc sources.

## STEP 0

You have to install the production libs and tools, you have to make available:

  • Python (v3+)

  • Sphinx (v3.2+) and all its associated libs (see below)

  • guzzle sphinx theme

To check your production configuration, open an Unix shell, for example bash and run the commands (do not type the $ sign which is supposed to be the shell prompt:

$ python
Python 3.9.1 (default, Feb  8 2021, 12:46:16)
[GCC 4.8.5 20150623 (Red Hat 4.8.5-16)] on linux
Type "help", "copyright", "credits" or "license" for more information.

If the python version is not 3.x.y or if you do not have python, you have to install it. On some systems, you would have to type python3 to run python instead of only python without version number.

Once python 3.x.y is there, go to STEP 2.


Now your python version is 3.x.y and you have to use the 3.x version in all path we mention in next steps. The example are using 3.7 and you should change these path with your own 3.x to make it work properly.

## STEP 1

The >>> sign is the python interpreter prompt. We resume our test by trying to find out if our python installation has all required packages:

>>> import sphinx
>>> import guzzle_sphinx_theme

If the command fails on import sphinx, you can install it using the shell command (not a python command):

$ pip install sphinx

If the command fails on the import guzzle_sphinx_theme you have to install the guzzle package. The guzzle theme can be found in the CGNS doc sources, you find the package in <clone-directory>/ You can find below an example installation of guzzle you have to modify to fit your own environment.

mkdir /tmp/gz
cp /tmp/gz
cd /tmp/gz
cd guzzle_sphinx_theme-master/
python build
mkdir /tmp/gz/install
export PYTHONPATH=/tmp/gz/install/lib/python3.7/site-packages/:$PYTHONPATH
python install --prefix=/tmp/gz/install

Once you have installed guzzle, make sure the Python .egg file is uncompressed. For example, on a Unix platform with a sh shell:

cd /tmp/gz/install/lib/python3.7/site-packages
unzip guzzle_sphinx_theme-0.7.11-py3.7.egg

If you still have an error in import guzzle_sphinx_theme you can move the page this way:

cd /tmp/gz/install/lib/python3.7/site-packages
mv guzzle_sphinx_theme-0.7.11-py3.7.egg/guzzle_sphix_theme .

Try again this STEP 1 if succeed, you jump to STEP 2

## STEP 2

Congrats! you are now ready to contribute to the CGNS documentation. We retrieve the last version from the git repository. Go to the directory where you want to produce the documentation, say for example: /my/own/local/doc/directory

cd /my/own/local/doc/directory
git clone
git checkout doc-rest-migration


You need to have git to get the actual documentation source tree. We cannot detail here how to install git or how to allow it to access to the CGNS repository. If you really are lost, please use CGNS mailing list.

## STEP 3

Everything is ready now, once you are in /my/own/local/doc/directory all sources are in:



If this directory is not there, be sure you are on the doc-rest-migration branch.

Most of the files to be created/edited are rst files located in and below CGNS-ReST-site/source/

To produce the documentation, you run:

cd CGNS-ReST-site
sh ./

All doc is generated into:


To check the produced documentation, you open a web browser (chrome, firefox, whatever…) and you open the top page which is index.html (in this example we are still in the CGNS-ReST-site):

firefox ../../

Second you run the script, it generates all the stuff and copies a final/ usable html directory with all required files. You can copy this directory at any place you want, the directory is self-contained.

The equation rendering makes a reference to an external link, so that you may have issues with the equations if you are not connected to the public internet.

## STEP 4

Now you open your favorite text editor. You follow the documentation editing recommendations described hereafter and you loop on steps 3 and 4.

## STEP 5

You are done with your editing. You commit your changes with a nice comment and you push it to the repository:

git add -A
git commit -m 'update section 4.2.1'
git push


If some modifications have been applied since you where editing, you have to perform a merge by yourself after a git pull

Documentation editing

Doc Conventions for these CGNS web pages

Top level header

Second level

Third level

Fourth level

Fith level

The index is generated, you just have to mention an index entry in the text. For example, if you wan to add a reference to boundary condition in the index, you add:

:index:`Reference-state` data is useful for situations
where :index:`boundary-condition`
is not provided, and flow solvers are free to enforce any
appropriate boundary condition equations.

You note in this example we also add an index for the reference-state. We have now an entry boundary-condition and an entry reference-state.

We can use a similar to add two entries at the same time. In that case you have an entry boundary-condition in the index at reference-state and vice-versa.

Reference-state data is useful for situations
where :index:`index entries <pair: boundary-condition; reference-state>`
is not provided, and flow solvers are free to enforce any
appropriate boundary condition equations.

An internal link is composed of its anchor (the place in the web site where you want to go to) and a reference (the words wich triggers the jump to the anchor).

An anchor is defined with:

.. _ThisIsThePlaceYouWantToJumpTo:

Note the leading underscode and the single colon. The anchor test should be contiguous and we suggest using the camel case syntax.

The actual link is inserted with:

You read this text with your eyes but you
can also :ref:`click on to jump elsewhere <ThisIsThePlaceYouWantToJumpTo>`.

The anchor in into angular brackets, the clickable text is user defined.

For an external reference the syntax is:

Info can be found on `other site web page < URL to other site page >`_.

Do not miss the trailing underscore.

To add a quote in the text, inside a box (this is the default style of our template), shift the text block on the right:

Generating documentation from source code is possible.

   But code does not explain by itself

   -- C compiler (stdout)

Generating documentation from source code is possible.

But code does not explain by itself

—C compiler (stdout)


Header with 2 cols


Data :
  • cfl

  • rms

  1. a

  2. b



K Epsilon

A set of special blocks are called admonitions. These includes notes, warnings… their layout, again, is set by the style we use.

.. note::

   if you do not read the doc

.. warning::

   no way you succeed

.. tip::

   start from first page


if you do not read the doc


no way you succeed


start from first page

There are several ways to insert an image. The first example adds an image as a new paragraph:

.. image:: ../path/to/image/file.png
   :width: 200px
   :align: center

The second way is to inline the image so that it appears in the text without creating a new paragraph. You have to declare the image using a label enclosed with vertical bars:

.. |inline_image_label| image:: ../../path/to/image/file.png

Then you refer to thus label in the text where you want the insertion:

When you read this text you have an image like |inline_image_label| without
any break.


Preferred image formats are .png, .jpg, .gif or even .svg.


Image file path is relative to current doc directory and should refer to the images directory where all images are. It is sometimes a bit difficult to find out which is the level of directory you are into. You have to go back to the root directory of the doc generation, you add as many ../ as you entered directories up to your file. The root directory is the one where you can see or source.

For example, if you are editing source/standard/SIDS/convention.rst an image path should have three backwards items, ../../.. which are related to source/standard/SIDS.

Your image in this file has the path: ../../../images/sids/figs/bar_2.png

Inserting footnotes, citation or any reference can be defined in several ways:

In the text you can add references such as [2]_, [1]_, [CIT2002]_.

.. [2] In the footnote.

.. [1] A footnote contains body elements, consistently
   indented by at least 3 spaces.

.. [CIT2002] Just like a footnote, except the label is

In the text you can add references such as 2, 1, [CIT2002].


In the footnote.


A footnote contains body elements, consistently indented by at least 3 spaces.


Just like a footnote, except the label is textual.

CPEX guidelines

The CPEX process requires multiple docs.

The CPEX should include the following information:

  • Name(s) and organization(s) of proposer(s)

  • E-mail contact information

  • General description of extension

  • Reason or need for extension

  • A SIDS detailed description of extension using similar documentation style found in the SIDS

  • File Mapping description of Node Attributes, following the prescription given in existing Node Description Documentation

  • Specific example(s) of extension