Improvements to documentation generation and test NuGet package updat…

…es (#95)

.github/workflows/ci-cd.yml

@@ -132,7 +132,7 @@ jobs:
       run:
         working-directory: docs/github-pages
     env:
-      docfx_version: 2.76.0
+      docfx_version: 2.77.0
 
     # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
     permissions:
@@ -161,18 +161,20 @@ jobs:
           dotnet-version: 8.x
       - name: Install DocFx
         run: dotnet tool update -g docfx --version ${{ env.docfx_version }}
-      - name: Generate XrefMap
-        run: _scripts/generate-xrefmap.sh
+      - name: Get GitHub Pages Url
+        run: |
+          pages_url=$(gh api "repos/$GITHUB_REPOSITORY/pages" --jq '.html_url')
+          echo "gh_pages_url=$pages_url" >> $GITHUB_ENV
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Generate Xrefmap
+        run: _scripts/generate-xrefmap.sh ${{ env.gh_pages_url }}
       - name: Set Google Analytics Id
         run: jq --arg gaId "${{ vars.GA_TAG_ID }}" '.build.globalMetadata._googleAnalyticsTagId = $gaId' docfx.json > temp.json && mv temp.json docfx.json
-      - name: DocFx Metadata
-        run: docfx metadata docfx.json
-      - name: Remove Extension Methods
-        run: _scripts/remove-extn-method.sh
+      - name: Generate Metadata
+        run: _scripts/generate-metadata.sh
       - name: DocFx Build
         run: docfx build docfx.json
-      - name: Fix Xref Links
-        run: _scripts/fix-xref-links.sh
       - name: Upload Doc Artifacts
         uses: actions/upload-pages-artifact@v3
         with:

docs/github-pages/README.md

@@ -8,7 +8,7 @@ The documentation is powered by [Docfx](https://dotnet.github.io/docfx/). Docs a
 
 - Install the .NET Core SDK that the project is using.
 - Install [Docfx](https://dotnet.github.io/docfx/). The project version can be found in [ci-cd.yml](../../.github/workflows/ci-cd.yml) file.
-- Install bash. If you are on Windows, you can use Git Bash.
+- Bash. If you are on Windows, you can use Git Bash or WSL.
 
 To build the documentation run the following command in the github-pages folder:
 
@@ -17,3 +17,9 @@ _scripts/local-doc-gen.sh
 ```
 
 The script will perform some clean up, run `docfx` to generate the documentation and then serve it on `http://localhost:8080`. You can then preview the documentation in your browser.
+
+To serve the documentation with a different port, you can pass the port number as an argument to the script:
+
+```bash
+_scripts/local-doc-gen.sh 8081
+```

docs/github-pages/_scripts/generate-metadata.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+readonly metadata_file_dir="api-docs"
+
+change_netstd2_uids() {
+    local -r file_dir="$metadata_file_dir/netstd2"
+
+    # Loop through all yaml files in the api-docs/netstd2 folder
+    for file in $(find $file_dir -name "*.yml" -o -name "*.yaml"); do
+        # Update the uid property to prefix with netstd2.
+        sed -i "s|uid: |uid: netstd2.|g" $file
+
+        # Update text that contains <xref href="Dapper. to <xref href="netstd2.Dapper.
+        sed -i "s|<xref href=\"Dapper.SimpleSqlBuilder.|<xref href=\"netstd2.Dapper.SimpleSqlBuilder.|g" $file
+    done
+}
+
+remove_extension_methods() {
+    # Block of text to remove
+    local -r pattern="- h4: Extension Methods"
+
+    # Loop through all yaml files in the api-docs folder
+    for file in $(find $metadata_file_dir -name "*.yml" -o -name "*.yaml"); do
+        # Ignore file starts with toc
+        if [[ $file == *"toc.yml"* ]] || [[ $file == *"toc.yaml"* ]]; then
+            continue
+        fi
+
+        # Use sed to remove the block of text
+        sed -i "/$pattern/,+3d" "$file"
+    done
+}
+
+docfx metadata docfx.json
+change_netstd2_uids
+remove_extension_methods

docs/github-pages/_scripts/generate-xrefmap.sh

@@ -1,8 +1,36 @@
 #!/bin/bash
 
+if [ -z "$1" ]; then
+    echo "Error: Base URL not provided" >&2
+    exit 1
+fi
+
+## Assign the first argument to base_url and remove trailing slash if present
+readonly base_url=${1%/}
+
+readonly gen_folder="_xref-gen"
+readonly file_path="xrefs"
+
+# Copy and update xrefmap files with base URL in href property.
+copy_and_update_xrefmap_files() {
+    local -r files=("core.xrefmap.yml" "netstd2.xrefmap.yml")
+
+    for file in "${files[@]}"; do
+        # Copy file to xrefs folder
+        cp -f "$gen_folder/$file" "$file_path"
+
+        # Update href property in xrefmap file with base URL
+        sed -i "/href: http/!s|href: |href: $base_url/|g" "$file_path/$file"
+
+        # Update uid property in netstd2.xrefmap.yml to prefix with netstd2.
+        if [ "$file" == "netstd2.xrefmap.yml" ]; then
+            sed -i "s|uid: |uid: netstd2.|g" "$file_path/$file"
+        fi
+    done
+}
+
 docfx metadata docfx-xref.json
 docfx build docfx-xref.json
-cp -f _xref-gen/core.xrefmap.yml xrefs
-cp -f _xref-gen/netstd2.xrefmap.yml xrefs
-rm -r _xref-gen
-rm -r api-docs
+copy_and_update_xrefmap_files
+rm -r $gen_folder
+rm -r api-docs

docs/github-pages/_scripts/local-doc-gen.sh

@@ -1,6 +1,21 @@
 #!/bin/bash
 
-script_dir=$(dirname $0)
+set -e
+
+readonly default_port=8080
+readonly script_dir=$(dirname $0)
+
+# Read port number from the first argument, use default port if not provided
+readonly port=${1:-$default_port}
+
+# Validate port
+if ! [[ $port =~ ^[0-9]+$ ]] ; then
+   echo "Error: Port must be a number" >&2
+   exit 1
+fi
+
+readonly base_url="http://localhost:$port"
+echo "Base URL: $base_url"
 
 # Remove Existing Documentation
 if [ -d "_site" ]; then
@@ -11,20 +26,14 @@ if [ -d "api-docs" ]; then
   rm -r api-docs
 fi
 
-# Generate Generate XrefMap
-$script_dir/generate-xrefmap.sh
+# Generate Xrefmap
+$script_dir/generate-xrefmap.sh $base_url
 
 # Generate Metadata
-docfx metadata docfx.json
-
-# Remove Extension Methods
-$script_dir/remove-extn-method.sh
+$script_dir/generate-metadata.sh
 
 # Build Documentation
 docfx build docfx.json
 
-# Fix Xref Links
-$script_dir/fix-xref-links.sh
-
 # Serve Documentation
-docfx serve _site
+docfx serve _site --port $port

docs/github-pages/docfx.json

@@ -56,7 +56,8 @@
     ],
     "resource": [
       {
-        "files": ["/images/**"]
+        "files": ["/images/**"],
+        "exclude": ["_site/**", "obj/**"]
       }
     ],
     "xref": [

docs/github-pages/docs/advanced-features/parameter-properties.md

@@ -9,7 +9,7 @@ var builder = SimpleBuilder.Create($"SELECT * FROM User WHERE Id = @id")
     .AddParameter("id", value: id, dbType: DbType.Int32);
 ```
 
-However, the library also provides an extension method, [`DefineParam`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Extensions.SimpleParameterInfoExtensions.yml#Dapper_SimpleSqlBuilder_Extensions_SimpleParameterInfoExtensions_DefineParam__1___0_System_Nullable_System_Data_DbType__System_Nullable_System_Int32__System_Nullable_System_Byte__System_Nullable_System_Byte__), to streamline this process when using interpolated strings.
+However, the library also provides an extension method, [`DefineParam`](xref:Dapper.SimpleSqlBuilder.Extensions.SimpleParameterInfoExtensions.DefineParam``1(``0,System.Nullable{System.Data.DbType},System.Nullable{System.Int32},System.Nullable{System.Byte},System.Nullable{System.Byte})), to streamline this process when using interpolated strings.
 
 ```csharp
 using Dapper.SimpleSqlBuilder.Extensions;
@@ -29,7 +29,7 @@ var fluentBuilder = SimpleBuilder.CreateFluent()
     .Where($"Id = {id.DefineParam(dbType: DbType.Int32)}");
 ```
 
-The [`DefineParam`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Extensions.SimpleParameterInfoExtensions.yml#Dapper_SimpleSqlBuilder_Extensions_SimpleParameterInfoExtensions_DefineParam__1___0_System_Nullable_System_Data_DbType__System_Nullable_System_Int32__System_Nullable_System_Byte__System_Nullable_System_Byte__) extension method enables you to define the [`DbType`](xref:System.Data.DbType), `Size`, `Precision` and `Scale` of your parameter. This should only be used for parameters passed into the interpolated string, as the <xref:System.Data.ParameterDirection> is always set to `Input` for values in the interpolated string.
+The [`DefineParam`](xref:Dapper.SimpleSqlBuilder.Extensions.SimpleParameterInfoExtensions.DefineParam``1(``0,System.Nullable{System.Data.DbType},System.Nullable{System.Int32},System.Nullable{System.Byte},System.Nullable{System.Byte})) extension method enables you to define the [`DbType`](xref:System.Data.DbType), `Size`, `Precision` and `Scale` of your parameter. This should only be used for parameters passed into the interpolated string, as the <xref:System.Data.ParameterDirection> is always set to `Input` for values in the interpolated string.
 
 For cases where you don't want to use the extension method, you can manually create the parameter object:
 

docs/github-pages/docs/builders/builder.md

@@ -1,10 +1,10 @@
 # Builder
 
-The [`Builder`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml) is a versatile tool for constructing static, dynamic, complex SQL queries, and stored procedures.
+The [`Builder`](xref:Dapper.SimpleSqlBuilder.Builder) is a versatile tool for constructing static, dynamic, complex SQL queries, and stored procedures.
 
-The `Create` method on the [`SimpleSqlBuilder`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.SimpleBuilder.yml) or [`ISimpleBuilder`](../../api-docs/di/Dapper.SimpleSqlBuilder.DependencyInjection.ISimpleBuilder.yml) (when using [dependency injection](../configuration/dependency-injection.md)) creates a new [`builder`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml) instance. It accepts a SQL query as one of its parameters and returns a new [`builder`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml) instance.
+The `Create` method on the [`SimpleSqlBuilder`](xref:Dapper.SimpleSqlBuilder.SimpleBuilder.Create(System.FormattableString,System.String,System.Nullable{System.Boolean})) or [`ISimpleBuilder`](xref:Dapper.SimpleSqlBuilder.DependencyInjection.ISimpleBuilder.Create(System.FormattableString,System.String,System.Nullable{System.Boolean})) (when using [dependency injection](../configuration/dependency-injection.md)) creates a new [`Builder`](xref:Dapper.SimpleSqlBuilder.Builder) instance. It accepts a SQL query as one of its parameters and returns a new [`Builder`](xref:Dapper.SimpleSqlBuilder.Builder) instance.
 
-The SQL query can be a static string or an interpolated string. The [`builder`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml) parses the SQL query and extracts the parameters from it. The parameters can be accessed via the [`Parameters`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml#Dapper_SimpleSqlBuilder_Builder_Parameters) property, and the generated SQL query can be accessed via the [`Sql`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml#Dapper_SimpleSqlBuilder_Builder_Sql) property.
+The SQL query can be a static string or an interpolated string. The [`Builder`](xref:Dapper.SimpleSqlBuilder.Builder) parses the SQL query and extracts the parameters from it. The parameters can be accessed via the [`Parameters`](xref:Dapper.SimpleSqlBuilder.Builder.Parameters) property, and the generated SQL query can be accessed via the [`Sql`](xref:Dapper.SimpleSqlBuilder.Builder.Sql) property.
 
 ## Static SQL
 
@@ -71,7 +71,7 @@ SELECT * FROM User WHERE UserTypeId = @p0 AND Age >= @p1
 
 ### Builder Chaining
 
-If you prefer an alternative to interpolated string concatenation, you can use the [`Append`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml#Dapper_SimpleSqlBuilder_Builder_Append_Dapper_SimpleSqlBuilder_AppendInterpolatedStringHandler__), [`AppendIntact`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml#Dapper_SimpleSqlBuilder_Builder_AppendIntact_Dapper_SimpleSqlBuilder_AppendIntactInterpolatedStringHandler__), and [`AppendNewLine`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml#Dapper_SimpleSqlBuilder_Builder_AppendNewLine_Dapper_SimpleSqlBuilder_AppendNewLineInterpolatedStringHandler__) methods, which can be chained.
+If you prefer an alternative to interpolated string concatenation, you can use the [`Append`](xref:Dapper.SimpleSqlBuilder.Builder.Append(Dapper.SimpleSqlBuilder.AppendInterpolatedStringHandler@)), [`AppendIntact`](xref:Dapper.SimpleSqlBuilder.Builder.AppendIntact(Dapper.SimpleSqlBuilder.AppendIntactInterpolatedStringHandler@)), and [`AppendNewLine`](xref:Dapper.SimpleSqlBuilder.Builder.AppendNewLine(Dapper.SimpleSqlBuilder.AppendNewLineInterpolatedStringHandler@)) methods, which can be chained.
 
 ```csharp
 int userTypeId = 4;
@@ -124,7 +124,7 @@ ORDER BY FirstName, LastName
 
 ### Insert
 
-You can perform INSERT operations with the [`builder`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml) as seen in the example below.
+You can perform INSERT operations with the [`Builder`](xref:Dapper.SimpleSqlBuilder.Builder) as seen in the example below.
 
 ```csharp
 var user = new User { FirstName = "John", LastName = "Doe", UserTypeId = 4 };
@@ -146,7 +146,7 @@ VALUES (@p0, @p1, @p2)
 
 ### Update
 
-You can perform UPDATE operations with the [`builder`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml) as seen in the example below.
+You can perform UPDATE operations with the [`Builder`](xref:Dapper.SimpleSqlBuilder.Builder) as seen in the example below.
 
 ```csharp
 int id = 1;
@@ -183,7 +183,7 @@ DELETE FROM User WHERE Id = @p0
 
 ## Stored Procedures
 
-You can execute stored procedures with the [`builder`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml) as seen in the example below.
+You can execute stored procedures with the [`Builder`](xref:Dapper.SimpleSqlBuilder.Builder) as seen in the example below.
 
 ```csharp
 var user = new User { FirstName = "John", LastName = "Doe", UserTypeId = 4 };
@@ -205,7 +205,7 @@ int result = builder.GetValue<int>("Result");
 
 ## Builder Reset
 
-There are scenarios where you may want to reuse the [`builder`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml) without creating a new instance. This can be achieved by calling the [`Reset`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml#Dapper_SimpleSqlBuilder_Builder_Reset) method on the [`builder`](../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml) instance as seen in the example below.
+There are scenarios where you may want to reuse the [`Builder`](xref:Dapper.SimpleSqlBuilder.Builder) without creating a new instance. This can be achieved by calling the [`Reset`](xref:Dapper.SimpleSqlBuilder.Builder.Reset) method on the [`Builder`](xref:Dapper.SimpleSqlBuilder.Builder) instance as seen in the example below.
 
 ```csharp
 int id = 1;

docs/github-pages/docs/builders/dapper-comparison.md

@@ -69,3 +69,7 @@ var users = connection.Query<User>(fluentBuilder.Sql, fluentBuilder.Parameters);
 ```
 
 ---
+
+## Next Steps
+
+- [Performance](../miscellaneous/performance.md)

docs/github-pages/docs/builders/fluent-builder/delete-builder.md

@@ -1,6 +1,6 @@
 # Delete Builder
 
-You can perform `DELETE` operations with the [`Delete Builder`](../../../api-docs/netcore/Dapper.SimpleSqlBuilder.FluentBuilder.IDeleteBuilderEntry.yml) as seen in the example below.
+You can perform `DELETE` operations with the [`Delete Builder`](xref:Dapper.SimpleSqlBuilder.FluentBuilder.IDeleteBuilderEntry) as seen in the example below.
 
 ```csharp
 int id = 10;

docs/github-pages/docs/builders/fluent-builder/fluent-builder.md

@@ -1,10 +1,10 @@
 # Fluent Builder
 
-The [`Fluent Builder`](../../../api-docs/netcore/Dapper.SimpleSqlBuilder.FluentBuilder.ISimpleFluentBuilder.yml) enables you to build dynamic SQL queries using fluent APIs, offering a more intuitive and readable way to construct complex SQL statements.
+The [`Fluent Builder`](xref:Dapper.SimpleSqlBuilder.FluentBuilder.ISimpleFluentBuilder) enables you to build dynamic SQL queries using fluent APIs, offering a more intuitive and readable way to construct complex SQL statements.
 
-The `CreateFluent` method on the [`SimpleSqlBuilder`](../../../api-docs/netcore/Dapper.SimpleSqlBuilder.SimpleBuilder.yml) or [`ISimpleBuilder`](../../../api-docs/di/Dapper.SimpleSqlBuilder.DependencyInjection.ISimpleBuilder.yml) (when using [dependency injection](../../configuration/dependency-injection.md)) creates a new [`fluent builder`](../../../api-docs/netcore/Dapper.SimpleSqlBuilder.FluentBuilder.ISimpleFluentBuilder.yml) instance.
+The `CreateFluent` method on the [`SimpleSqlBuilder`](xref:Dapper.SimpleSqlBuilder.SimpleBuilder.CreateFluent(System.String,System.Nullable{System.Boolean},System.Nullable{System.Boolean})) or [`ISimpleBuilder`](xref:Dapper.SimpleSqlBuilder.DependencyInjection.ISimpleBuilder.CreateFluent(System.String,System.Nullable{System.Boolean},System.Nullable{System.Boolean})) (when using [dependency injection](../../configuration/dependency-injection.md)) creates a new [`fluent builder`](xref:Dapper.SimpleSqlBuilder.FluentBuilder.ISimpleFluentBuilder) instance.
 
-Using fluent APIs, you can build `SELECT`, `INSERT`, `UPDATE`, and `DELETE` queries. The [`fluent builder`](../../../api-docs/netcore/Dapper.SimpleSqlBuilder.FluentBuilder.ISimpleFluentBuilder.yml) parses the SQL query and extracts parameters from it. These parameters can be accessed via the [`Parameters`](../../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml#Dapper_SimpleSqlBuilder_Builder_Parameters) property, and the generated SQL query is available through the [`Sql`](../../../api-docs/netcore/Dapper.SimpleSqlBuilder.Builder.yml#Dapper_SimpleSqlBuilder_Builder_Sql) property.
+Using fluent APIs, you can build `SELECT`, `INSERT`, `UPDATE`, and `DELETE` queries. The [`Fluent builder`](xref:Dapper.SimpleSqlBuilder.FluentBuilder.ISimpleFluentBuilder) parses the SQL query and extracts parameters from it. These parameters can be accessed via the [`Parameters`](xref:Dapper.SimpleSqlBuilder.Builder.Parameters) property, and the generated SQL query is available through the [`Sql`](xref:Dapper.SimpleSqlBuilder.Builder.Sql) property.
 
 ## Fluent Builders
 

docs/github-pages/docs/builders/fluent-builder/insert-builder.md

@@ -1,6 +1,6 @@
 # Insert Builder
 
-You can perform `INSERT` operations with the [`Insert Builder`](../../../api-docs/netcore/Dapper.SimpleSqlBuilder.FluentBuilder.IInsertBuilderEntry.yml) as seen in the example below.
+You can perform `INSERT` operations with the [`Insert Builder`](xref:Dapper.SimpleSqlBuilder.FluentBuilder.IInsertBuilderEntry) as seen in the example below.
 
 ```csharp
 var user = new User { FirstName = "John", LastName = "Doe", UserTypeId = 4 };