Documentation

The main MESA documentation lives in $MESA_DIR/docs and is generated using Sphinx.

Once you have installed Sphinx, you can generate the docs by doing

cd $MESA_DIR/docs
make html

You can then view the docs in your browser by visiting the URL file://<MESA_DIR>/docs/build/html/index.html (replace <MESA_DIR> with the appropriate path).

File Locations

The main body of the docs lives in $MESA_DIR/docs/source. However, some documentation lives outside of the docs subdirectory so that it can be close to the code that it documents.

That documentation can then be incorporated into the main docs either by symlinking the file into the docs tree in an appropriate location or by using ..include:: <filename> statements.

Examples of documentation that lives elsewhere include:

  • The defaults files live in <module>/defaults/ are symlinked into docs and also pre-processed (see Format for MESA defaults files).
  • The README.rst file in each test suite case (which is included in docs/test_suite).

Style

This describes the style conventions used in the MESA documentation.

Here is a link to a reStructured Text primer.

Click “View page source” in the upper right to see the rst file corresponding to this page.

The Format for MESA defaults files page has additional information on ReST formatting from the perspective of writing defaults files.

Cross-references

These docs use the autosectionlabel Sphinx extension along with the settings (see conf.py):

autosectionlabel_prefix_document = True
autosectionlabel_maxdepth = 3

This means that you can refer to sections by their title. However, sections are disambiguated by their location in the docs. For example, this section has the label developing/documentation:Cross-references.

Names

Write module names as literals. My favorite module is eos.

Option names also literals like my_option. Ideally someday these would become hyperlinks to their reference entries.

References

References should be written in the usual astrophysics style – like Dotter et al. (2009) – and hyperlinked to either their ADS entry (preferred) or a DOI.

Symbols

Common astrophysics symbols have substitutions already defined in conf.py.

Symbol Substitution
\({\rm M}_\odot\) |Msun|
\({\rm L}_\odot\) |Lsun|
\({\rm R}_\odot\) |Rsun|
\(T_{\rm eff}\) |Teff|
\(\chi^2\) |chi^2|

Instrument Papers

Instrument papers should be indicated using the abbreviated form MESA I, etc. (This is achieved using the substitution |MESA I|.)