classicvalues / mesa-website

Jekyll-based website for the MESA stellar evolution code

MESA Website

This is the source code of the website for the MESA stellar evolution code.

You can view the site here.

NOTE: Much of the content on this website is being migrated into the MESA documentation website, which is generated from the MESA GitHub repository. Most non-news updates should happen there.

Contributing

Did you find an error? Do you see something that can be improved? Do you have other materials you’ve written yourself that you think could be incorporated? If so, you can clone this repo and send a pull request.

NOTE: Given the switch to the Sphinx documentation, contributions there are preferred.

Branching and Merging

There are two branches.

maint

This branch contains the public version of the site. Pull requests which fix problems spotted at mesa.sourceforge.net should be made against this branch. maint is merged into master at least as often as MESA is released.

git checkout master
git merge maint

master

This branch contains changes which should be published in the next MESA release. master is merged into maint at the time of a new MESA release.

git checkout maint
git merge --ff-only master

There has not yet been a need for development on a longer timescale than that, so there is not a separate dev branch.

Repository Layout

This site uses the jekyll static site generator.

??-<name>.markdown

These files are the main pages of the site. They are written in Markdown and then the HTML pages are generated from these files.

assets/

This directory contains images, movies, etc.

_config.yml

This file contains options to control the configuration of jekyll.

css/

This directory contains the CSS files. (They could use a good cleanup from someone who knows modern CSS.)

docs/

This directory contains the MESA defaults files. Each version gets its own sub-directory.

_includes/

This directory contains snippets like the site header (head.html), left side bar (leftside.html) and right news bar (news.html).

_layouts/

This directory has HTML templates that control the overall layout of the site.

_plugins/

This directory contains plug-ins (written in Ruby), which allow one to extend the functionality of jekyll.

_posts/

This directory contains a Markdown file for each of the MESA news posts that appear in the right hand sidebar.

_site/

This directory should not be under version control, but will be created once you run jekyll. It contains the static version of the website, which is what is copied to the sourceforge server.

Generating

If you’re making significant changes to the site, you probably want to see the effects of your changes as you go along. You can generate and view a version of the site on your own machine.

First, install a current version (2.3+) of ruby, using whichever tools are appropriate for your OS (e.g., port, brew, apt-get, pacman, etc.). This will come with rubygems (a ruby package manager).

Next, install the following gems. (Rubygems will take care of installing their dependencies).

gem install jekyll
gem install therubyracer
gem install nokogiri
gem install parslet

Then, clone this git repository.

git clone https://github.com/MESAHub/mesa-website

Now, change to the mesa-website directory and tell jekyll to serve a local copy of the site for you.

jekyll serve --watch

Visit 0.0.0.0:4000 in your web browser to see the site. As you edit the files, the site will be regenerated to reflect the changes you’ve made. Read the jekyll documentation to learn more.

Once you’ve finished making your changes, commit them.

Publishing

Previously, this site was auto-deployed to sourceforge after pushes to the maint branch. This process was triggered via git webhook and ran on a server controlled by Josiah. Now, this publication process needs to be triggered manually. The included file deploy-mesa-website (which was the script that Josiah’s server would run post-push) should provide a useful guide to the necessary steps. Essentially, one simply runs Jekyll locally to generate the static site and then copies the generated files to sourceforce using rsync.

Doing a MESA release

The following things need to be done when a new MESA release occurs.

Edit _config.yml

Update the version number to the current release.

Check the tutorial

Make a copy of the star/work directory and run the default inlists with the new MESA version. Check to make sure that the output roughly agrees with what is written in 03-staring.markdown. If not, update the tutorial to reduce possible confusion for new users.

Add a news post

Copy an existing release newspost (e.g., _posts/2014-06-08-r6596.markdown) and update the date and release number. Briefly summarize the release notes, mentioning any major changes or issues that require user intervention. Link to the mailing list post announcing the new release.

Update the defaults files

Copy the defaults files for the latest release.

mkdir docs/r?????
cp $MESA_DIR/star/defaults/*.defaults docs/r?????/

Now add the new version in to the DEFAULTS_VERSION variable the provided parser/converter (make_docs.rb). Then run it

ruby make_docs.rb

and check that it is successful.

Edit the docs index docs/index.markdown and add the new version to the listing. (This could probably be automated, though the defaults files haven’t been constant in name or number over the life of MESA.)

Commit the *.defaults files and the *.markdown files that were generated by the make_docs.rb script. The reason for re-generating everything is that it lets us take advantage of improvements made to the Markdown output. If not backwards-compatible changes are made, older versions can be removed from the version list and thus new *.markdown files will no longer be generated.

Upload a new zip file to sourceforge

Make a zip file of the latest release. Here’s an example script to do that.

do_one() {

    MESA_SVN=/home/jschwab/Software/mesa-svn
    MESA_FILENAME=mesa-r$1

    svn export -r $1 ${MESA_SVN} ${MESA_FILENAME}

    zip -r ${MESA_FILENAME}.zip ${MESA_FILENAME}
    rsync -e ssh ${MESA_FILENAME}.zip frs.sourceforge.net:/home/frs/project/mesa/releases

    rm ${MESA_FILENAME}.zip
    rm -rf ${MESA_FILENAME}

}

do_one 6596

If you need to adjust the modification date of the zipfile, here’s a sketch how to do so.

Get the modification date from the svn logs:

svn log -r 6596 ${MESA_SVN} | grep -oE "[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2} -[0-9]{4}"

Get a shell on sourceforge:

ssh -t jschwab,[email protected] create

In the shell, touch the file with the date:

touch --date="2014-06-06 19:30:30 -0700" mesa-r6596.zip