UCAIug CIM Modeling Guide, © 2019 - 2024. All rights reserved by the UCA International CIM Users Group
This repository hosts the publically available CIM Modeling Guide made available by the UCA International CIM Users Group. This official guide is managed and maintained by the CIM Model Management Team and can be viewed online here.
The final documentation published online is generated using Material for MkDocs.
For general questions or discussions related to this UCAIug publication or specific rules therein please post directly to the CIM Modeling Guide Discussion forums for this repository.
For any identified issues with this CIM Modeling Guide please submit them via the CIM Modeling Guide Issues tracker. Be sure to add an appropriate "version" label on your issue (e.g. v1.1) corresponding to the publication version of the modeling guide.
To run the site locally use Python. This is cleanest if you use a Python virtual environment as shown below to install the dependencies.
python -m venv venv
venv\Scripts\activate
pip install mkdocs-material mkdocs-with-pdf mike mkdocs-enumerate-headings-plugin
For exact (known working) versions of dependencies, run pip install -r requirements.txt
instead.
Once installed, you can then run the documentation site locally with mkdocs serve
mkdocs serve
You can view the site by navigating to http://localhost:8000 in your browser.
This project also publishes a PDF version of the site. The easiest way to generate the PDF is with the Generate CIM Modeling Guide PDF GitHub Action. However, if you need to run it locally, first set the ENABLE_PDF_EXPORT
environment variable then run the build command.
set ENABLE_PDF_EXPORT=1
mkdocs build
The output will indicate the PDF file location.
This project gets published to the https://cim-mg.ucaiug.io site. The easieset way update the site is with the Publish website GitHub Action.
You can also publish manually as described below. Under the hood the project is using GitHub Pages to host the site which effecitvely just stores the site content in a dedicated git branch called gh-pages
. It uses the mike plugin to publish multiple versions.
Update a version in the gh-pages
branch using the mike deploy [version]
command. This will replace the existing version of the documentation on the gh-pages
branch with whever the currently checkout version is and give it a label of [version]
. So for example to publish a new version of 1.0 you first want to pull the latest published changes down from the remote
git remote add upstream https://github.com/cimug-org/cim-modeling-guide
git fetch upstream
git switch gh-pages
git pull upstream gh-pages
Then switch to the branch you want to update and run the deploy command giving it the verion name you want, for example let's say we're going to publish version "1.0" which is in branch "v1.0".
git switch v1.0
git pull upstream v1.0
mike deploy 1.0
When you need to update which version is considered the "latest" (e.g. when going from 1.0 to 2.0) run the following
mike deploy 2.0 latest --update-aliases
Note that mike will always update the version and any aliases ("latest") when you run a mike deploy [version]
command. So you only need to do the mike deploy [version] latest --update-aliases
when the latest version is changed.
To view the site locally before publishing it to https://cim-mg.ucaiug.io, run
mike serve
Then to publish it to https://cim-mg.ucaiug.io, you will want to push your local gh-pages
branch to the remote https://github.com/cimug-org/cim-modeling-guide repo using
mike deploy 1.0 --push --branch gh-pages --remote upstream
Refer to mike documentation for more information.