CMS Wiki

The CMS Wiki is located at https://coecms.github.io/cms-wiki

... introduction ...

Chapters

...

Building the book

If you'd like to develop on and build the CLEX CMS Wiki book, you should:

• Clone this repository and run
• Run pip install -r requirements.txt (it is recommended you do this within a virtual environment)
• Run jupyter-book build Wiki/
• If you previously built the book, it is recommended to remove the existing Wiki/_build/ directory, before building again, so you will be able to see all potential warnings, instead of only the ones generated by recent changes. You can do this with jupyter-book clean Wiki/ jupyter-book clean Wiki/ --all will also remove the cache

A fully-rendered HTML version of the book will be built in Wiki/_build/html/.

Hosting the book

The html version of the book is hosted on the gh-pages branch of this repo. A GitHub actions workflow has been created that automatically builds and pushes the book to this branch on a push or pull request to main.

If you wish to disable this automation, you may remove the GitHub actions workflow and build the book manually by:

• Navigating to your local build; and running,
• ghp-import -n -p -f Wiki/_build/html

This will automatically push your build to the gh-pages branch. More information on this hosting process can be found here.

NB this should be now automated using github action defined in .github/workflows/deploy.yml Any commit to the main branch should trigger this action.

Contributing

To contribute new pages/updates to the book:

• clone the repository locally
• create a new branch
• once ready push your changes to github and open a pull request
• summarise your changes and assign at least one reviewer

As a reviewer

Depending on the magnitude of the changes it might be more efficient to pull the pull request branch locally and build the book from it. This is to avoid to approve changes that might break the book itself and spot any issue with rendering.

• clone the specific branch
• build the book
• push back your changes if any, or add comments to the request
• once satisfied approve the review and the branch can be merged, this will trigger the book deploy action

Adding new Sphinx Extensions

Sometimes you may want to use a Sphinx extension that isn't currently included in this book. To add it you will need to do 2 things.

1. Add the pip package to the requirements.txt file. If a specific version is needed, don't forget to also include it, i.e. jinja2==3.0.0.
2. You will also need to add the extension to the _config.yaml file so the book knows to load it. Add the extension name inside the extra_extenbsion like sphinx_inline_tabs is below:

sphinx:
  extra_extensions:
  - sphinx_inline_tabs

Credits

This project is created using the excellent open source Jupyter Book project and the executablebooks/cookiecutter-jupyter-book template.