Merge pull request #54 from FirelyTeam/add-cql-documentation

Added initial documentation for the CQL Engine.

cql.rst

@@ -0,0 +1,11 @@
+.. _cql:
+
+.. include:: cql/introduction.rst
+
+.. toctree::
+   :maxdepth: 3
+   :hidden:
+
+   Introduction <cql/introduction>
+   cql/cql-packager
+

cql/cql-packager.rst

@@ -0,0 +1,42 @@
+The CQL Packager tool
+---------------------
+
+The CQL Packager tool turns ELM files into C#. There are 
+
+- Converting ELM to C#
+- Creating FHIR `Library <https://hl7.org/fhir/library.html>`_ resources containing the CQL, ELM, C# and compiled code.
+
+The tool cannot, as of now, convert CQL into ELM, for this you need to use the existing `Java-based tooling <https://github.com/cqframework/clinical_quality_language/blob/master/Src/java/README.md#generate-an-elm-representation-of-cql-logic>`_.
+
+Installing the tool
+^^^^^^^^^^^^^^^^^^^
+The tool is distributed as a `dotnet tool`, so to install it, run 
+
+.. code-block:: powershell
+
+    dotnet tool install Hl7.Cql.Packager --global
+
+You can add ``--prerelease`` and ``--version`` to install a specific (prerelease) version of the tool.
+
+Running the tool
+^^^^^^^^^^^^^^^^
+Run the tool without arguments to display a help text:
+
+.. code-block:: powershell
+
+    cql-package
+
+There are the main commandline arguments to pass into the tool:
+
+- ``--elm``: an existing directory where the ELM files can be found. These files must have the ``.json`` suffix.
+- ``--cql``: an existing directory where the corresponding original CQL files can be found. These must have the ``.cql`` suffix.
+- ``--fhir``: a directory where the produced FHIR Library resources will be written to (in FHIR Json format). Though optional, without this argument you will not get any useful output. If the directory does not exist, it will be created.
+- ``--cs``: a directory where the generated C# will be written to. If the directory does not exist, it will be created.
+
+For example, if you have checked out the Demo project in the repo, running the tool like so will produce both libraries and source code:
+
+.. code-block:: powershell
+
+    cql-package --elm Elm\json --cql Cql\input --fhir c:\packager-output-fhir --cs c:\packager-output-cs
+
+Note that if the tool encounters any unparseable files, it will neatly report a stacktrace and exit.

cql/introduction.rst

@@ -0,0 +1,41 @@
+================
+Working with CQL
+================
+
+As a result of the cooperation between Firely and `NCQA <https://www.ncqa.org/>`_, the SDK contains a full CQL Engine
+and a tool to convert ELM-based CQL logic to C#.
+
+To start working with CQL, you need to do two things:
+
+- Install the CQL Packager .NET tool, which will allow you to read ELM files, turn them into C# and compile them. This is done by running ``dotnet tool install Hl7.Cql.Packager --global`` (add ``--prerelease`` if you are feeling adventurous).
+- Add a reference to the `main CQL package <https://www.nuget.org/packages/Hl7.Cql>`_ to your project.
+
+The packager tool will generate the C# that the engine can run using the engine. For example, if we had compiled a library called ``BCSEHEDISMY2022`` (version 1.0.0), the packager will create a class called ``BCSEHEDISMY2022_1_0_0`` that can be invoked like this:
+
+.. code-block:: csharp
+
+	using Hl7.Cql.Fhir;
+	using Hl7.Cql.Packaging;
+	using Hl7.Cql.Primitives;
+	using Hl7.Fhir.Model;
+
+	// Set up the parameters for the CQL library
+	private readonly IDictionary<string, object> MY2023 =
+	  new Dictionary<string, object>
+	  {
+		{
+		  "Measurement Period",
+			new CqlInterval<CqlDateTime>(
+			new CqlDateTime(2023, 1, 1, 0, 0, 0, 0, 0, 0),
+			new CqlDateTime(2023, 12, 31, 0, 0, 0, 0, 0, 0),
+			true,
+			true)
+		}
+	  };
+
+	var patientEverything = new Bundle();  // add some data
+	var context = FhirCqlContext.ForBundle(patientEverything, MY2023);
+	var bcs = new BCSEHEDISMY2022_1_0_0(context); // instantiate the library
+	var numerator = bcs.Numerator(); // invoke one of the definition in the library
+
+More information can be found in the `GitHub repository for the CQL Engine <https://github.com/FirelyTeam/firely-cql-sdk#getting-started>`_.

index.rst

@@ -16,6 +16,7 @@
    parsing
    validation
    fhirpath
+   cql
    package-source
    contact
    releasenotes