Bump docfx to 2.77.0 and adjust config (#357)

Author: roji

.github/workflows/build-documentation.yml

@@ -30,6 +30,7 @@ jobs:
       with:
         ref: live
         path: live
+
     - name: Clear live docs repo
       run: rm -rf live/*
 
@@ -40,29 +41,40 @@ jobs:
         ref: docs
         path: Npgsql
 
+    # Setup software
+    - name: Setup .NET Core
+      uses: actions/setup-dotnet@v4.0.1
+      with:
+        dotnet-version: 7.0.x
+
+    # docfx has issues specifically with analyzer/sourcegen projects; build manually before 
+    - name: Build Npgsql
+      run: dotnet build -c Release
+      shell: bash
+      working-directory: Npgsql
+
     - name: Checkout EFCore.PG
       uses: actions/checkout@v4
       with:
         repository: npgsql/Npgsql.EntityFrameworkCore.PostgreSQL
         ref: docs
         path: EFCore.PG
 
-    # Setup software
-    - name: Setup .NET Core
-      uses: actions/setup-dotnet@v4.0.1
-      with:
-        dotnet-version: 7.0.x
+    - name: Build EFCore.PG
+      run: dotnet build -c Release
+      shell: bash
+      working-directory: EFCore.PG
 
     # Note:
     # Since we use a custom template to override some properties of the docfx default template, when upgrading docfx we should check
     # whether the default template of the new docfx version has changes we need to carry over to our modified version.
     # You can get the docfx default template via the following command: docfx template export default
     # This will put the default template folder into a directory called _exported_templates
     - name: Get docfx
-      run: dotnet tool install --version 2.61.0 -g docfx
+      run: dotnet tool install --version 2.77.0 -g docfx
 
     - name: Build docs
-      run: docfx
+      run: docfx --warningsAsErrors
 
     - name: Commit and push
       if: (github.event_name == 'push' || github.event_name == 'repository_dispatch') && github.repository == 'npgsql/doc' && github.ref == 'refs/heads/main'

conceptual/EFCore.PG/index.md

@@ -133,7 +133,7 @@ builder.Services.AddDbContextPool<BloggingContext>(opt =>
             o => o.ConfigureDataSource(dataSourceBuilder => dataSourceBuilder.UseClientCertificate(certificate))));
 ```
 
-`ConfigureDataSource()` provides access to a lower-level [`NpgsqlDataSourceBuilder`](../doc/basic-usage.html#data-source) which you can use to configure all aspects of the Npgsql ADO.NET provider.
+`ConfigureDataSource()` provides access to a lower-level [`NpgsqlDataSourceBuilder`](../Npgsql/basic-usage.md#data-source) which you can use to configure all aspects of the Npgsql ADO.NET provider.
 
 > [!WARNING]
 > The EF provider internally creates an NpgsqlDataSource and uses that; for most configuration (e.g. connection string), the provider knows to switch between NpgsqlDataSources automatically.

conceptual/EFCore.PG/release-notes/8.0.md

@@ -189,9 +189,9 @@ Because of the NativeAOT and trimming work done for Npgsql 8.0 ([release notes](
 
 PostgreSQL type                          | Default .NET type
 ---------------------------------------- | --------------------------
-JSON POCO mapping, JsonNode and subtypes | <xref:Npgsql.INpgsqlTypeMapperExtensions.EnableDynamicJson>
-Unmapped enums, ranges, multiranges      | <xref:Npgsql.INpgsqlTypeMapperExtensions.EnableUnmappedTypes>
-Read PostgreSQL records as .NET tuples   | <xref:Npgsql.INpgsqlTypeMapperExtensions.EnableRecordsAsTuples>
+JSON POCO mapping, JsonNode and subtypes | <xref:Npgsql.TypeMapping.INpgsqlTypeMapper.EnableDynamicJson%2A>
+Unmapped enums, ranges, multiranges      | <xref:Npgsql.TypeMapping.INpgsqlTypeMapper.EnableUnmappedTypes%2A>
+Read PostgreSQL records as .NET tuples   | <xref:Npgsql.TypeMapping.INpgsqlTypeMapper.EnableRecordsAsTuples%2A>
 
 Existing code using the above features will start throwing exceptions after upgrading to version 8.0 of the EF Core provider; the exceptions provide explicit guidance on how to add the opt-ins.
 

conceptual/EFCore.PG/release-notes/9.0.md

@@ -9,7 +9,7 @@ Npgsql.EntityFrameworkCore.PostgreSQL version 9.0 is under development; previews
 
 The Npgsql EF provider is built on top of the lower-level Npgsql ADO.NET provider; the configuration interface between these two layers was less than ideal, and configuration been more difficult than it should have been. For version 9.0, the configuration experience has been considerably improved.
 
-Since version 7, the Npgsql ADO.NET provider has been moving to [NpgsqlDataSource](../../doc/basic-usage.html#data-source) as the preferred way of configuration connections and obtaining them. At the EF level, it has been possible to pass an NpgsqlDataSource instance to `UseNpgsql()`; but this required that the user separately configure a data source and manage it. In addition, features such as  plugins and enums require support from both the EF and ADO.NET layers, forcing users to perform multiple setup actions at the different layers.
+Since version 7, the Npgsql ADO.NET provider has been moving to [NpgsqlDataSource](../../Npgsql/basic-usage.md#data-source) as the preferred way of configuration connections and obtaining them. At the EF level, it has been possible to pass an NpgsqlDataSource instance to `UseNpgsql()`; but this required that the user separately configure a data source and manage it. In addition, features such as  plugins and enums require support from both the EF and ADO.NET layers, forcing users to perform multiple setup actions at the different layers.
 
 With version 9, `UseNpgsql()` becomes a single point for configuration, for both the EF and ADO.NET levels. EF can now internally set up an NpgsqlDataSource, automatically applying all the necessary configuration to it, and also exposes an API to allow users to apply arbitrary configuration to it as well:
 
@@ -31,7 +31,7 @@ In the above code, the following configuration gestures are performed:
 3. `MapEnum()` maps a .NET enum type. Like `UseNodaTime()`, this also used to require a separate ADO.NET configuration gesture, but is now done automatically. As an added bonus, doing this now also adds the enum to the model, causing the enum to be created in the database via EF's migrations.
 4. `ConfigureDataSource()` exposes an NpgsqlDataSourceBuilder, which you can use to configure arbitrary ADO.NET options. In this example, the certificate is defined for the TLS authentication process.
 
-For more information, see the [getting started docs](../index.html).
+For more information, see the [getting started docs](../index.md).
 
 ### Improved configuration for enums and plugins
 

conceptual/Npgsql/release-notes/4.0.md

@@ -36,7 +36,7 @@ You can now use the new [Npgsql.NodaTime](../types/nodatime.md) to have Npgsql m
 
 ## Json.NET
 
-Another plugin, [Npgsql.Json.NET](../types/jsonnet.md), works with [Newtonsoft Json.NET](https://www.newtonsoft.com/json) to automatically serialize and deserialize PostgreSQL's `jsonb` and `json` types to your objects, providing a seamless database JSON programming experience. Instead of working with strings which you have to serialize and deserialize, Npgsql does it for you.
+Another plugin, [Npgsql.Json.NET](../types/json.md), works with [Newtonsoft Json.NET](https://www.newtonsoft.com/json) to automatically serialize and deserialize PostgreSQL's `jsonb` and `json` types to your objects, providing a seamless database JSON programming experience. Instead of working with strings which you have to serialize and deserialize, Npgsql does it for you.
 
 ## Other improvements
 

conceptual/Npgsql/release-notes/8.0.md

@@ -53,12 +53,12 @@ For more information on registering Npgsql services in DI, see the documentation
 ## Other features
 
 * Allow using nullable value types with the generic `NpgsqlParameter<T>`, e.g. `NpgsqlParameter<int?>`.
-* Introduce a non-caching password provider callback via <xref:Npgsql.NpgsqlDataSourceBuilder.UsePasswordProvider?displayProperty=nameWithType>.
-* Allow customizing System.Text.Json JsonSerializationOptions via <xref:Npgsql.NpgsqlDataSourceBuilder.ConfigureJsonOptions?displayProperty=nameWithType>.
+* Introduce a non-caching password provider callback via <xref:Npgsql.NpgsqlDataSourceBuilder.UsePasswordProvider*?displayProperty=nameWithType>.
+* Allow customizing System.Text.Json JsonSerializationOptions via <xref:Npgsql.NpgsqlDataSourceBuilder.ConfigureJsonOptions*?displayProperty=nameWithType>.
 * Improvements and cleanup for networking type mappings:
   * In addition to .NET <xref:System.Net.IPAddress>, PostgreSQL `inet` can also mapped to be mapped to <xref:NpgsqlTypes.NpgsqlInet>, which is an immutable struct containing both IP and netmask components.
   * PostgreSQL `cidr` is now mapped to the newly-introduced <xref:NpgsqlTypes.NpgsqlCidr>. The mapping to `ValueTuple<IPAddress, int>` has been removed.
-* Allow providing the root certificate programmatically via the new <xref:Npgsql.NpgsqlDataSourceBuilder.UseRootCertificate?displayProperty=nameWithType>
+* Allow providing the root certificate programmatically via the new <xref:Npgsql.NpgsqlDataSourceBuilder.UseRootCertificate*?displayProperty=nameWithType>
 
 Version 8.0 contains many other smaller features and bug fixes, [see the 8.0.0 milestone](https://github.com/npgsql/npgsql/milestone/97?closed=1) for the full list of issues.
 
@@ -70,9 +70,9 @@ Npgsql 8.0 is fully compatible with NativeAOT and trimming (see above). While mo
 
 PostgreSQL type                          | Default .NET type
 ---------------------------------------- | --------------------------
-JSON POCO mapping, JsonNode and subtypes | <xref:Npgsql.INpgsqlTypeMapperExtensions.EnableDynamicJson>
-Unmapped enums, ranges, multiranges      | <xref:Npgsql.INpgsqlTypeMapperExtensions.EnableUnmappedTypes>
-Read PostgreSQL records as .NET tuples   | <xref:Npgsql.INpgsqlTypeMapperExtensions.EnableRecordsAsTuples>
+JSON POCO mapping, JsonNode and subtypes | <xref:Npgsql.TypeMapping.INpgsqlTypeMapper.EnableDynamicJson%2A>
+Unmapped enums, ranges, multiranges      | <xref:Npgsql.TypeMapping.INpgsqlTypeMapper.EnableUnmappedTypes%2A>
+Read PostgreSQL records as .NET tuples   | <xref:Npgsql.TypeMapping.INpgsqlTypeMapper.EnableRecordsAsTuples%2A>
 
 Existing code using the above features will start throwing exceptions after upgrading to Npgsql 8.0; the exceptions provide explicit guidance on how to add the opt-ins.
 

conceptual/Npgsql/security.md

@@ -80,7 +80,7 @@ If the root CA of the server certificate isn't installed in your machine's CA st
 
 Note that Npgsql does not perform certificate revocation validation by default, since this is an optional extension not implemented by all providers and CAs. To turn on certificate revocation validation, specify `Check Certificate Revocation=true` on the connection string.
 
-Finally, if the above options aren't sufficient for your scenario, you can call <xref:Npgsql.NpgsqlDataSourceBuilder.UseUserCertificateValidationCallback(System.Net.Security.RemoteCertificateValidationCallback)?displayProperty=nameWithType> to provide your custom server certificate validation logic (this gets set on the underlying .NET [`SslStream`](https://docs.microsoft.com/dotnet/api/system.net.security.sslstream.-ctor#System_Net_Security_SslStream__ctor_System_IO_Stream_System_Boolean_System_Net_Security_RemoteCertificateValidationCallback_System_Net_Security_LocalCertificateSelectionCallback_)).
+Finally, if the above options aren't sufficient for your scenario, you can call <xref:Npgsql.NpgsqlDataSourceBuilder.UseUserCertificateValidationCallback*?displayProperty=nameWithType> to provide your custom server certificate validation logic (this gets set on the underlying .NET [`SslStream`](https://docs.microsoft.com/dotnet/api/system.net.security.sslstream.-ctor#System_Net_Security_SslStream__ctor_System_IO_Stream_System_Boolean_System_Net_Security_RemoteCertificateValidationCallback_System_Net_Security_LocalCertificateSelectionCallback_)).
 
 ### Client certificates
 
@@ -92,7 +92,7 @@ PostgreSQL may be configured to require valid certificates from connecting clien
 
 To provide a password for a client certificate, set either the `SSL Password` (6.0 and higher) or `Client Certificate Key` (5.0 and lower) connection string parameter.
 
-Finally, you can call <xref:Npgsql.NpgsqlDataSourceBuilder.UseClientCertificate(System.Security.Cryptography.X509Certificates.X509Certificate)?displayProperty=nameWithType>, <xref:Npgsql.NpgsqlDataSourceBuilder.UseClientCertificates(System.Security.Cryptography.X509Certificates.X509CertificateCollection)?displayProperty=nameWithType> or <xref:Npgsql.NpgsqlDataSourceBuilder.UseClientCertificatesCallback(System.Action{System.Security.Cryptography.X509Certificates.X509CertificateCollection})?displayProperty=nameWithType> to programmatically provide a certificate, multiple certificates or a callback which returns certificates (this works like on the underlying .NET [`SslStream`](https://docs.microsoft.com/dotnet/api/system.net.security.sslstream.-ctor#System_Net_Security_SslStream__ctor_System_IO_Stream_System_Boolean_System_Net_Security_RemoteCertificateValidationCallback_System_Net_Security_LocalCertificateSelectionCallback_)).
+Finally, you can call <xref:Npgsql.NpgsqlDataSourceBuilder.UseClientCertificate*?displayProperty=nameWithType>, <xref:Npgsql.NpgsqlDataSourceBuilder.UseClientCertificates*?displayProperty=nameWithType> or <xref:Npgsql.NpgsqlDataSourceBuilder.UseClientCertificatesCallback*?displayProperty=nameWithType> to programmatically provide a certificate, multiple certificates or a callback which returns certificates (this works like on the underlying .NET [`SslStream`](https://docs.microsoft.com/dotnet/api/system.net.security.sslstream.-ctor#System_Net_Security_SslStream__ctor_System_IO_Stream_System_Boolean_System_Net_Security_RemoteCertificateValidationCallback_System_Net_Security_LocalCertificateSelectionCallback_)).
 
 > [!NOTE]
 > Npgsql supports .PFX and .PEM certificates starting with 6.0. Previously, only .PFX certificates were supported.

conceptual/Npgsql/types/json.md

@@ -46,7 +46,7 @@ With this mapping style, you're fully responsible for serializing/deserializing
 
 If your column JSON contains documents with a stable schema, you can map them to your own .NET types (or POCOs). The provider will use System.Text.Json APIs under the hood to serialize instances of your types to JSON documents before sending them to the database, and to deserialize documents coming back from the database. This effectively allows mapping an arbitrary .NET type - or object graph - to a single column in the database.
 
-Starting with Npgsql 8.0, to use this feature, you must first enable it by calling <xref:Npgsql.INpgsqlTypeMapperExtensions.EnableDynamicJson> on your <xref:Npgsql.NpgsqlDataSourceBuilder>, or, if you're not yet using data sources, on `NpgsqlConnection.GlobalTypeMapper`:
+Starting with Npgsql 8.0, to use this feature, you must first enable it by calling <xref:Npgsql.TypeMapping.INpgsqlTypeMapper.EnableDynamicJson*> on your <xref:Npgsql.NpgsqlDataSourceBuilder>, or, if you're not yet using data sources, on `NpgsqlConnection.GlobalTypeMapper`:
 
 ### [NpgsqlDataSource](#tab/datasource)
 

docfx.json

@@ -3,27 +3,27 @@
     {
       "src": [
         {
-          "files": [ "src/**/*.csproj" ],
+          "files": [ "src/Npgsql/Npgsql.csproj" ],
           "exclude": [ "src/MSI/**", "src/VSIX/**", "**/bin/**", "**/obj/**" ],
-          "cwd": "Npgsql/"
+          "src": "Npgsql/"
         }
       ],
       "dest": "obj/api/Npgsql",
       "properties": {
-        "TargetFramework": "netstandard2.1"
+        "TargetFramework": "net8.0"
       }
     },
     {
       "src": [
         {
           "files": [ "src/**/*.csproj" ],
           "exclude": [ "**/bin/**", "**/obj/**", "Properties/NpgsqlStrings.*" ],
-          "cwd": "EFCore.PG"
+          "src": "EFCore.PG"
         }
       ],
       "dest": "obj/api/EFCore.PG",
       "properties": {
-        "TargetFramework": "net6.0"
+        "TargetFramework": "net8.0"
       }
     }
   ],
@@ -35,27 +35,27 @@
     "content": [
       {
         "files": [ "**/*.yml" ],
-        "cwd": "obj/api/Npgsql",
+        "src": "obj/api/Npgsql",
         "dest": "doc/api"
       },
       {
         "files": [ "**/*.yml" ],
-        "cwd": "obj/api/EFCore.PG",
+        "src": "obj/api/EFCore.PG",
         "dest": "efcore/api"
       },
       {
         "files": [ "**.md", "toc.yml" ],
-        "cwd": "conceptual/Npgsql",
+        "src": "conceptual/Npgsql",
         "dest": "doc"
       },
       {
         "files": [ "**.md", "toc.yml" ],
-        "cwd": "conceptual/EFCore.PG",
+        "src": "conceptual/EFCore.PG",
         "dest": "efcore"
       },
       {
         "files": [ "**.md", "toc.yml" ],
-        "cwd": "conceptual/EF6.PG",
+        "src": "conceptual/EF6.PG",
         "dest": "ef6"
       },
       {