Tutorials For Developers

Some tutorials for developers.

How To Do A Release

  1. Write down the release_notes:

    1. in rST format: realeas_notes_XYZ.rst

    2. Start with a summary Main Changes (TL;DR version of the whole file)

    3. add all issues and PR related references

    4. add list of contributors

    5. add list of perspectives and tag contributors

  2. Release an alpha version:

    1. Create an annotaded tag (do not use GitHub’s release system) git tag -a X.Y.Z-alpha0 -m "annotation"

    2. Update the version of the repo: python -c "import _updateversion as up; out = up.updateversion(); print(out)"

    3. push on GitHub server

    4. Verify that ONE build passes on travis: the deployment on conda should pass for all travis-build, but for pypi only the first build will pass

    5. Install it locally on all available platforms and environments (by hand), with all different packaging tools. And try some tests.

    6. Easybuild: try to create a tarball for Jira machines

    7. For IRFM servers, build the conda_recipe by hand:

      $ if [[ "$TRAVIS_PYTHON_VERSION" == "3.7-dev" ]]; then export VADD="py37"; else export VADD="py36";  fi
$ export CONDA_BLD_PATH=$(pwd)/conda-bld/ # you should be in the tofu dir
$ export REV=$(python -c "import _updateversion as up; out=up.updateversion(); print(out)")
$ export VERSION=$(echo $REV | tr - .)
$ echo $REV

  3. Update the releases.rst file in the web documentation:

    1. create a symbolic link from $TOFU_DIR/release_notes/release_notes_XYZ.rst to $TOFU_DIR/doc/source/release_notes/release_notes_XYZ.rst

    2. Update the .rst file

    3. Make and publish doc (see tutorial below)

  4. Release the real version:

    1. Follow the same steps as for alpha version, just change the tag and annotation.

  5. Send an email to users.

How To Construct The Doc

Adding text, updating the API:

  1. The easiest way is to have two different repo: $TOFU_DIR, for building the doc and $TOFU_DIR/../test_doc/tofu/ for seeing the resulting html (always in the gh-pages branch)

  2. If updating the API, make sure that you have installed the right version of tofu

  3. Change to the new-doc branch

  4. Go to $ cd $TOFU_DIR/doc/

  5. Modify the corresponding file (somewhere in src/a-file.rst)

  6. If you added a file

  7. sphinx-apidoc -Mf -P -d 5 -o source/ ../tofu/ {../*test*,../*mag*,../*imas2tofu*,../*geom/inputs}

  8. $ make clean (to make sure only the needed files will be stored)

  9. $ make html

  10. Go to the gh-pages branch and open the index.html file (from the top)

  11. Commit and push the changes to the new-doc branch: to keep the changes in the sources

  12. Commit and push the changes to the gh-pages, this will update the website.

Adding a tutorial:

  1. Add your tutorial in $TOFU_DIR/examples/tutorials with the proper naming conventions

  2. The sphinx gallery is automatically updated when building the doc (as above)

  3. Change the index.rst file to include a thumbnail of your tutorial