Merge 3e19e37 into 80f1db7

.github/workflows/cmake-multi-platform.yml

@@ -57,7 +57,7 @@ jobs:
         egress-policy: audit
 
     - name: Checkout Repository
-      uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2
 
     # add problem matchers by compiler
     - name: Add Problem Matchers
@@ -148,7 +148,7 @@ jobs:
       run: cmake --build --preset ${{matrix.preset}}
 
     - name: Checkout OdbDesign Test Data Repository
-      uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1      
+      uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2
       with:
         repository: 'nam20485/OdbDesignTestData'
         path: 'OdbDesignTestData'

.github/workflows/codeql.yml

@@ -48,7 +48,7 @@ jobs:
         egress-policy: audit
 
     - name: Checkout repository
-      uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL

.github/workflows/create-release.yml

@@ -44,7 +44,7 @@ jobs:
               fi
     
           - name: Checkout Repository
-            uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+            uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2
 
           - name: Download Artifacts
             uses: dawidd6/action-download-artifact@09f2f74827fd3a8607589e5ad7f9398816f540fe # v3.1.4

.github/workflows/dependency-review.yml

@@ -30,7 +30,7 @@ jobs:
           egress-policy: audit
 
       - name: 'Checkout Repository'
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2
 
       - name: Component detection 
         uses: advanced-security/component-detection-dependency-submission-action@5a8ce4ad8c6fbb9b88f66f672014e44b427d7d54 # v0.0.2       

.github/workflows/docker-publish.yml

@@ -42,7 +42,7 @@ jobs:
           egress-policy: audit
 
       - name: Checkout repository
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2
 
       # add problem matchers
       - name: Add Problem Matchers
@@ -112,7 +112,7 @@ jobs:
       # https://github.com/docker/build-push-action
       - name: Build and push Docker image
         id: build-and-push
-        uses: docker/build-push-action@af5a7ed5ba88268d5278f7203fb52cd833f66d6e
+        uses: docker/build-push-action@2cdde995de11925a030ce8070c3d77a52ffcf1c0
         with:
           context: .          
           push: ${{ github.event_name != 'pull_request' }}

.github/workflows/docker-scout-scan.yml

@@ -48,7 +48,7 @@ jobs:
           egress-policy: audit
 
       - name: Checkout repository
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2
 
       # add problem matchers
       - name: Add Problem Matchers
@@ -89,7 +89,7 @@ jobs:
       # https://github.com/docker/build-push-action
       - name: Build and push Docker image
         id: build-and-push
-        uses: docker/build-push-action@af5a7ed5ba88268d5278f7203fb52cd833f66d6e
+        uses: docker/build-push-action@2cdde995de11925a030ce8070c3d77a52ffcf1c0
         with:
           context: .          
           push: false

.github/workflows/jekyll-gh-pages.yml

@@ -32,7 +32,7 @@ jobs:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2        
 
       - name: Install Doxygen
         run: sudo apt install -y doxygen

.github/workflows/sbom-generate-submit.yml

@@ -23,7 +23,7 @@ jobs:
           egress-policy: audit
 
       - name: Checkout Code
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2
 
       - name: SBOM Generate
         uses: advanced-security/sbom-generator-action@375dee8e6144d9fd0ec1f5667b4f6fb4faacefed # v0.0.1

.github/workflows/scorecard.yml

@@ -40,7 +40,7 @@ jobs:
           egress-policy: audit
 
       - name: "Checkout code"
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2
         with:
           persist-credentials: false
 

docs/README.md

@@ -2,6 +2,24 @@
 
 A free open source cross-platform C++ library for parsing ODB++ Design archives, accessing their data, and building net list product models. Exposed via a REST API packaged inside of a Docker image.
 
+## Skip to Build and Running Instructions
+
+Sounds great! Now how do I build and run it?
+
+[Run](#running)
+
+[Build](#building-from-source)
+
+Documentation for the currently-released version of the source code is available [here](https://nam20485.github.io/OdbDesign/api).
+
+## Need Help?
+
+Feel free to message me in the project's Gitter chat room: [odbdesign:gitter.im](https://app.gitter.im/#/room/#odbdesign:gitter.im)
+
+You can also create an issue: <https://github.com/nam20485/OdbDesign/issues>
+
+Or you can start a discussion: <https://github.com/nam20485/OdbDesign/discussions>
+
 ## Key Features
 
 OdbDesign ODB++ parser is differentiated from other offerings by these key features:
@@ -96,14 +114,49 @@ The diagram describes the current state of parser implementation and data availa
 
 The OdbDesign parser is built as a C++ shared library on all three platforms. An executable running the server links to the library and provides the REST API for accessing the data the library parses. The REST API server can be run by invoking the executable directly or by running the Docker image. The server executable and library can be run on Windows, Linux, or MacOS and the Docker image can be run on any platform that supports Docker.
 
+Documentation for the currently-released version of the source code is available [here](https://nam20485.github.io/OdbDesign/api).
+
 [Insert Diagram Image]
 
 #### Library
 
 FileModel vs. ProductModel...
 
+## Running
+
+There are three different ways to use the project. You can:
+
+1. Build the C++ shared library and use it in your own application
+1. Build the C++ library and REST API server application and then run the application
+1. Run the REST API server (which contains the library inside) from the Docker image.
+
+The instructions for building the C++ shared library and application are below in the [Building from Source](#building-from-source) section. The instructions for running the application or REST API server are here.
+
+### Running the C++ Application
+
+The C++ application REST API server can be run by executing the `OdbDesignServer` or `OdbDesignServer.exe` executable (depending on your platform).
+
+The executable can be found in the following directory:
+
+* `~/src/OdbDesign/out/build/x64-release`                         *(Linux/MacOS)*
+* `C:\Users\<YourName>\Source\OdbDesign\out\build\x64-release`    *(Windows)*
+
+See the [Building from Source](#building-from-source) section for more details on building the C++ application and the build output directory.
+
+If successful, the REST API server will be running and listening on port 8888. You can access the REST API at `http://localhost:8888`.
+
+### Running the REST API Server
+
+From the root of the source directory run:
+
+`$ docker compose up`
+
+If successful, the REST API server will be running and listening on port 8888. You can access the REST API at `http://localhost:8888`. The Swagger UI is available at `http://localhost:8080/swagger`.
+
 ## Building from Source
 
+Documentation for the currently-released version of the source code is available [here](https://nam20485.github.io/OdbDesign/api).
+
 ### Build Dependencies
 
 > If you are building on Windows and have a modern version of Visual Studio installed then all of the dependencies listed below are already installed on your system (except for maybe Docker). You can skip to the next section.
@@ -123,7 +176,7 @@ FileModel vs. ProductModel...
 Get the source code by cloning the GitHub repository:
 
 ```Bash
-$ git clone git@github.com:nam20485/OdbDesign.git
+$ git clone https://github.com/nam20485/OdbDesign.git
 ```
 
 ### Build
@@ -165,22 +218,37 @@ $ cmake --build --preset linux-release
 
 ```
 
+This builds the C++ shared library and the REST API server executable. See the [Running the C++ Application](#running-the-c%2b%2b-application) section for more details.
+
+The build output can be found in the following directory:
+
+* `~/src/OdbDesign/out/build/x64-release`                         *(Linux/MacOS)*
+* `C:\Users\<YourName>\Source\OdbDesign\out\build\x64-release`    *(Windows)*
+
+>The `x64-release` directory will be different if you selected a different configuration preset (`x64-release` vs. `x64-debug` or `linux-release` vs. `linux-debug`). The `x64-release` directory will contain the shared library and the server executable. Make sure to copy the dependencies (.dll files on Windows, .so files on Linux, .dylib files on MacOS) to the same directory as the executable if you want to copy it somewhere else.
+
 #### Docker Image for REST API Server
 
+From the root of the source directory...
+
 ```Bash
-$ docker build . -t odbdesign-server
+$ docker compose up
 ```
 
-## Running the REST API Server
+This builds the Docker image and runs it. See the [Running the REST API Server](#running-the-rest-api-server) section for more details.
 
 ## Integration into Other Applications
 
-There are three interfaces that allow use of the library in other applications.
+There are three separate interfaces that allow use of the library in other applications.
 
 ### C++ Shared Library
 
+Build the C++ shared library and link it into your own C++ application. See the [Building from Source](#building-from-source) section for more details on building it.
+
 ### REST API
 
+Run the REST API server and access the data via the REST API. See the [Running the REST API Server](#running-the-rest-api-server) section for more details on running it.
+
 ### Google Protobuf Protocol Buffers
 
 Data objects returned from the parser library support serialization to and from [Google Protobuf protocol buffers](https://protobuf.dev/). This allows the data to be easily shared with other applications and programming languages that support protocol buffers. Google Protobuf is a highly optimized binary encoding so it is fast and small.
@@ -224,6 +292,7 @@ If you are interested in using the parser in your application or code, or have a
 * [GitHub](https://github.com/nam20485/odbdesign)
 * [LinkedIn](https://www.linkedin.com/in/namiller/)
 * [OdbDesign Website](https://nam20485.github.io/OdbDesign/)
+* Gitter chat room: [odbdesign:gitter.im](https://app.gitter.im/#/room/#odbdesign:gitter.im)
 
 ## ODB++