V1.1

.github/workflows/generate-pdf.yml

@@ -1,32 +1,23 @@
 name: Generate CIM Modeling Guide PDF
-on:
-  push:
-  release:
-    types: [published]
-  pull_request:
-    branches: [ "master" ]
+on: workflow_dispatch
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout this repository
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
     - name: Install/setup Python
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5
       with:
-        python-version: 3.x
-    - name: Install mkdocs documentation tool
-      run: pip install mkdocs-material
-    - name: Install PDF export plugin dependency (Pango)
-      run: sudo apt install libpango-1.0-0 libharfbuzz0b libpangoft2-1.0-0
-    - name: Install PDF export plugin for mkdocs
-      run: pip install mkdocs-pdf-export-plugin
+        python-version: 3.9
+    - name: Install mkdocs documentation tool and plugins
+      run: pip install -r requirements.txt
     - name: Build the documentation including PDF
       run: mkdocs build
       env:
         ENABLE_PDF_EXPORT: 1
     - name: Upload CIM Modeling Guide PDF as artifact
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: CIM_Modeling_Guide.pdf
-        path: site/CIM_Modeling_Guide.pdf
+        path: site/pdf/CIM_Modeling_Guide.pdf

.github/workflows/publish-site.yml

@@ -0,0 +1,27 @@
+name: Publish website
+on: workflow_dispatch
+permissions:
+  contents: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout this repository
+      uses: actions/checkout@v4
+
+    - name: Install/setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.9
+
+    - name: Install mkdocs documentation tool and plugins
+      run: pip install -r requirements.txt
+
+    - name: Configure Deploy
+      run: |
+        git config --global user.name "Admin CIMug"
+        git config --global user.email "cimug.dev@gmail.com"
+        git fetch origin gh-pages --depth=1
+
+    - name: Build Docs Website
+      run: mike deploy --branch gh-pages --remote origin --push 1.1

.gitignore

@@ -0,0 +1,2 @@
+site/
+venv/

README.md

@@ -1,24 +1,72 @@
 # CIM Modeling Guide
-UCAIug CIM Modeling Guide, © 2019 - 2023. All rights reserved by the UCA International CIM Users Group
+
+![image](docs/images/media/image-header-1.png)
+
+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](https://cim-mg.ucaiug.io/).
 
+The final documentation published online is generated using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material).
+
+## CIM Modeling Guide Discussion Forums
+
+For general questions or discussions related to this UCAIug publication or specific rules therein please post directly to the [CIM Modeling Guide Discussion](https://github.com/cimug-org/cim-modeling-guide/discussions) forums for this repository.
+
+## Submitting Issues
+For any identified issues with this **CIM Modeling Guide** please submit them via the [CIM Modeling Guide Issues](https://github.com/cimug-org/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.
+
 ## Contributing
-CIM Modeling Guide is documented using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material). If you need to do work on the CIM Modeling Guide you can do so by editing the files directly in the `docs` folder of this repo. 
+To run the site locally use [Python](https://www.python.org/). This is cleanest if you use a Python virtual environment as shown below to install the dependencies.
+```cmd
+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`
+```cmd
+mkdocs serve
+```
+You can view the site by navigating to http://localhost:8000 in your browser.
 
-## Offline Viewing
-There are two options for offline viewing of the latest CIM Modeling Guide. You can download the latest release of the PDF of the CIM Modeling Guide at [releases](https://github.com/cimug-org/cim-modeling-guide/releases). 
+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](https://github.com/cimug-org/cim-modeling-guide/actions/workflows/generate-pdf.yml) GitHub Action. However, if you need to run it locally, first set the `ENABLE_PDF_EXPORT` environment variable then run the build command.
 
-Alternatively, to serve the modeling guide locally as a live-reloading web page, use [Docker](https://www.docker.com/) or [Python](https://www.python.org/).
+```cmd
+set ENABLE_PDF_EXPORT=1
+mkdocs build
+```
+The output will indicate the PDF file location.
 
-For Docker, do `docker pull squidfunk/mkdocs-material` then `mkdocs serve` is default command so you can just do the following from repo root to start the site:
+## Publishing
+This project uses the [mike](https://github.com/jimporter/mike) plugin to publish multiple versions of the documentation to the https://cim-mg.ucaiug.io site. Under the hood it is using [GitHub Pages](https://pages.github.com/) to host the site which effecitvely just stores the site content in a dedicated git branch called `gh-pages`. 
 
-    docker run --rm -it -p 127.0.0.1:8000:8000/tcp -v %CD%:/docs squidfunk/mkdocs-material
+You can push new versions 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 site
+```cmd
+git remote add origin https://github.com/cimug-org/cim-modeling-guide
+git fetch origin
+git switch gh-pages
+git pull origin gh-pages
+```
+Then switch to the branch you want to update and run the deploy command giving it the name you want, for example let's say we're going to publish version "1.0" which is in branch "v1.0".
+```cmd
+git switch v1.0
+mike deploy 1.0
+```
 
-For Python, do `pip install mkdocs-material` then once installed, the basic commands are:
+When you need to update which version is considered the "latest" (e.g. when going from 1.0 to 2.0) run the following
+```cmd
+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 -u [version] latest` when the latest version is changed.
 
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site (for deployment).
-* `mkdocs -h` - Print help message and exit.
+To view the site locally before publishing it to https://cim-mg.ucaiug.io, run
+```cmd
+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
+```cmd
+mike deploy 1.0 --push
+```
 
-Once you have it running with either Docker or Python, you can view it by navigating to http://localhost:8000 on your browser.
+Refer to [mike documentation](https://github.com/jimporter/mike) for more information.

docs/index.md

@@ -8,34 +8,36 @@
 
 **13-February-2021**
 
+The PDF release of v1.1 of the CIM Modeling Guide is made available [here](https://cimug.org/cimdocs/model-manager-documents/?wpcp_link=JTdCJTIyc291cmNlJTIyJTNBJTIyNjVmNzM0NTkyN2U5OTk1YjliZDI0YzlmOTBjNWJhMWMlMjIlMkMlMjJhY2NvdW50X2lkJTIyJTNBJTIyMTg2MDYxNzEwNTYlMjIlMkMlMjJsYXN0Rm9sZGVyJTIyJTNBJTIyMzA3OTY4MzMwMzc0JTIyJTJDJTIyZm9sZGVyUGF0aCUyMiUzQSUyMld5SXpNRGM1Tmpnek16QXpOelFpWFElM0QlM0QlMjIlMkMlMjJmb2N1c19pZCUyMiUzQSUyMjE3ODA3MjMwMjYzMjElMjIlN0Q%3D) at the UCAIug SharePoint site.
 
 !!! Note
 
     When referencing an offline PDF version of this guide note that it may not correspond to the latest publicly available guide. To reference the latest visit [https://cim-mg.ucaiug.io](https://cim-mg.ucaiug.io).
 
+    The PDF release of v1.1 of the CIM Modeling Guide is made available [here](https://cimug.ucaiug.org/Model%20Manager%20Documents/Public/CIM%20Modeling%20Guide_v1.1.pdf) at the UCAIug SharePoint site or [here](https://github.com/cimug-org/cim-modeling-guide/releases/download/v1.1/CIM_Modeling_Guide_v1.1.pdf) at the UCAIug's official Github site.
+
 
 **UCA International Users Group**
 
+### RIGHT TO DISTRIBUTE AND CREDIT NOTICE
 
-> **RIGHT TO DISTRIBUTE AND CREDIT NOTICE**
->
-> This material was created by the UCA International Users Group CIM Model Managers and is available for public use and distribution. Please include credit in the following manner, “UCAIug CIM Modeling Guide, Version 1.1, © November 2021. All rights reserved by the UCA International Users Group”.
+> This material was created by the UCA International Users Group CIM Model Managers and is available for public use and distribution. Please include credit in the following manner, “UCAIug CIM Modeling Guide, Version 1.1, © February 2021. All rights reserved by the UCA International Users Group”.
 
-DISCLAIMER OF WARRANTIES AND LIMITATION OF LIABILITIES
+### DISCLAIMER OF WARRANTIES AND LIMITATION OF LIABILITIES
 
 > THIS DOCUMENT is a work product of THE UCA International Users Group. it was prepared by the CIM Model Managers and approved by the UCA International Users Group leadership. NEITHER the CIM Model Managers, the UCA International Users Group leadership, the CIM users group, NOR ANY PERSON ACTING ON BEHALF OF ANY OF THEM:
 >
-> \(A\) MAKES ANY WARRANTY OR REPRESENTATION WHATSOEVER, EXPRESS OR IMPLIED, (I) WITH RESPECT TO THE USE OF ANY INFORMATION, APPARATUS, METHOD, PROCESS, OR SIMILAR ITEM DISCLOSED IN THIS DOCUMENT, INCLUDING MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, OR (II) THAT SUCH USE DOES NOT INFRINGE ON OR INTERFERE WITH PRIVATELY OWNED RIGHTS, INCLUDING ANY PARTY'S INTELLECTUAL PROPERTY, OR (III) THAT THIS DOCUMENT IS SUITABLE TO ANY PARTICULAR USER'S CIRCUMSTANCE; OR
+> (A) MAKES ANY WARRANTY OR REPRESENTATION WHATSOEVER, EXPRESS OR IMPLIED, (I) WITH RESPECT TO THE USE OF ANY INFORMATION, APPARATUS, METHOD, PROCESS, OR SIMILAR ITEM DISCLOSED IN THIS DOCUMENT, INCLUDING MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, OR (II) THAT SUCH USE DOES NOT INFRINGE ON OR INTERFERE WITH PRIVATELY OWNED RIGHTS, INCLUDING ANY PARTY'S INTELLECTUAL PROPERTY, OR (III) THAT THIS DOCUMENT IS SUITABLE TO ANY PARTICULAR USER'S CIRCUMSTANCE; OR
 >
-> \(B\) ASSUMES RESPONSIBILITY FOR ANY DAMAGES OR OTHER LIABILITY WHATSOEVER (INCLUDING ANY CONSEQUENTIAL DAMAGES, EVEN IF the UCA International Users Group OR ANY UCA International Users Group REPRESENTATIVE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES) RESULTING FROM YOUR SELECTION OR USE OF THIS DOCUMENT OR ANY INFORMATION, APPARATUS, METHOD, PROCESS, OR SIMILAR ITEM DISCLOSED IN THIS DOCUMENT.
+> (B) ASSUMES RESPONSIBILITY FOR ANY DAMAGES OR OTHER LIABILITY WHATSOEVER (INCLUDING ANY CONSEQUENTIAL DAMAGES, EVEN IF the UCA International Users Group OR ANY UCA International Users Group REPRESENTATIVE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES) RESULTING FROM YOUR SELECTION OR USE OF THIS DOCUMENT OR ANY INFORMATION, APPARATUS, METHOD, PROCESS, OR SIMILAR ITEM DISCLOSED IN THIS DOCUMENT.
 >
-> \(C\) Reference herein to any specific commercial process, or service by its trade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by the UCA International Users Group.
+> (C) Reference herein to any specific commercial process, or service by its trade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by the UCA International Users Group.
 
-THIRD PARTY INTELLECTUAL PROPERTY
+### THIRD PARTY INTELLECTUAL PROPERTY
 
-> The CIM standards are a set of International Electrotechnical Committee (IEC) standards and are the Intellectual Property of the IEC. the UCA International Users Group has a liaison d relationship with the iec that provides access rights to the cim standards for software development. the common information model (CIM) is Open Source and is rendered in the Unified Modeling Language.
+> The CIM standards are a set of International Electrotechnical Committee (IEC) standards and are the Intellectual Property of the IEC. The UCA International Users Group has a Liaison D relationship with the IEC that provides access rights to the CIM standards for software development. The Common Information Model (CIM) is Open Source and is rendered in the Unified Modeling Language.
 
-<span style="font-size:2.0em;">Acknowledgements</span>
+## Acknowledgements
 
 In preparing this specification, the UCAIug recognizes the special contributions of the following CIM Subcommittee and their organizations.
 
@@ -55,19 +57,19 @@ In preparing this specification, the UCAIug recognizes the special contributions
 
 - Tatjana Kostic - *ABB*
 
-<span style="font-style:italic;font-size:2.0em;">Abstract</span>
+## *Abstract*
 
 > *This document specifies the rules and recommendations on how to use the UML to create and maintain a standardized Common Information Model (CIM) of the electric grid and other related business domains. Such models are called Domain Models. The primary goal of this document is to facilitate communication and understanding among people working with the CIM domain models. The primary goal of the rules is to specify the structure and modeling constraints applied to the CIM. The primary goal of the recommendations is to provide guidelines on how to extend the CIM as more of the model is elaborated by working groups within the International Electrotechnical Commission (IEC) and by the CIM user community. The intent of the recommendations is to facilitate the incorporation of new model elements into the CIM.*
 
-<span style="font-size:2.0em;">Foreword</span>
+## Foreword
 
 Exchanging power systems data between utility companies is always problematic when proprietary formats are used. In the past a company would traditionally use a single software system, whether it is a custom in-house solution, or purchased from a large software company, and there would be a single proprietary data standard and format used. With the deregulation of the power industry and the emergence of smarter grids, there is now a greater need to be able to share such power system data between companies and systems.
 
 The increase in choice provided by the number of power system software vendors and the different software packages and architectures available add to the challenge of data exchange. These issues point to a requirement for a single, open standard for describing power system data and to aid the interoperability between software packages and exchange of information both within one company and between companies.
 
 The Common Information Model (CIM) is an open standard for representing power system components originally developed by the Electric Power Research Institute (EPRI) in North America. The CIM provides the basis of a series of standards developed under the auspices of the International Electrotechnical Commission (IEC). The CIM standard was started as part of the Control Centre Application Programming Interface (CCAPI) project at EPRI with the aim of defining a common definition for the components in power systems for use the Energy Management System (EMS) Application Programming Interface (API). The EMS API is now maintained by IEC Technical Committee 57 Working Group 13 as IEC 61970-301. The format has been adopted by the major EMS vendors to allow the exchange of data between their applications, independent of their internal software architecture or operating platform.[^1]
 
-<span style="font-size:2.0em;">About the UCA International CIM Users Group</span>
+## About the UCA International CIM Users Group
 
 The UCA International Users Group (UCAIug) is a not-for-profit corporation focused on assisting users and vendors in the deployment of standards for real-time applications for several industries with related requirements. The UCAIug does not write standards, however it works closely with those bodies that have primary responsibility for the completion of standards (notably IEC TC 57: *Power Systems Management and Associated Information Exchange*).
 

docs/revision-history.md

@@ -0,0 +1,7 @@
+# Revision History
+
+| **Rev. #** | **Rev Date** | **Author** | **Description** | 
+|------------|--------------|------------|-----------------| 
+| 1.0 | 25-Nov-2019 | H. Dotson, et al. | Initial Release | 
+| 1.1 | 13-Feb-2021 | H. Dotson, et al. | Update to Rule 197 | 
+