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).
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
docsand also pre-processed (see Format for MESA defaults files).
README.rstfile in each test suite case (which is included in
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.
These docs use the autosectionlabel
Sphinx extension along with the settings (see
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
Write module names as literals. My favorite module is
Option names also literals like
my_option. Ideally someday these
would become hyperlinks to their reference entries.
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.
Common astrophysics symbols have substitutions already defined in