Merge branch 'main' into chore-add-support-for-forked-repository

Author: filzrev

.github/workflows/nightly.yml

@@ -0,0 +1,30 @@
+name: nightly
+on:
+  schedule:
+  - cron: '0 0 * * *'
+
+jobs:
+  publish-github-packages:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+ 
+    - id: version
+      uses: paulhatch/semantic-version@v5.4.0
+      with:
+        version_format: ${major}.${minor}.${patch}-preview.${increment}
+
+    - uses: ./.github/actions/build
+    
+    - name: dotnet pack
+      run: dotnet pack -c Release /p:Version=${{ steps.version.outputs.version }} -o drop/nuget
+
+    - name: dotnet nuget push
+      run: |
+        dotnet nuget push drop/nuget/*.nupkg --api-key "${{ secrets.GITHUB_TOKEN }}" --skip-duplicate --source https://nuget.pkg.github.com/dotnet/index.json
+

Directory.Packages.props

@@ -8,8 +8,8 @@
     <PackageVersion Include="ICSharpCode.Decompiler" Version="8.2.0.7535" />
     <PackageVersion Include="IgnoresAccessChecksToGenerator" Version="0.7.0" />
     <PackageVersion Include="Jint" Version="3.0.1" />
-    <PackageVersion Include="JsonSchema.Net" Version="6.0.4" />
-    <PackageVersion Include="Markdig" Version="0.35.0" />
+    <PackageVersion Include="JsonSchema.Net" Version="6.0.7" />
+    <PackageVersion Include="Markdig" Version="0.36.2" />
     <PackageVersion Include="Microsoft.CodeAnalysis" Version="4.9.2" />
     <PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="4.9.2" />
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.9.2" />
@@ -23,7 +23,7 @@
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
     <PackageVersion Include="OneOf" Version="3.0.263" />
     <PackageVersion Include="OneOf.SourceGenerator" Version="3.0.263" />
-    <PackageVersion Include="PdfPig" Version="0.1.9-alpha-20240312-845e3" />
+    <PackageVersion Include="PdfPig" Version="0.1.9-alpha-20240324-e7896" />
     <PackageVersion Include="PlantUml.Net" Version="1.4.80" />
     <PackageVersion Include="Spectre.Console" Version="0.48.0" />
     <PackageVersion Include="Spectre.Console.Cli" Version="0.48.0" />
@@ -37,7 +37,7 @@
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
     <PackageVersion Include="PublicApiGenerator" Version="11.1.0" />
     <PackageVersion Include="Verify.DiffPlex" Version="2.3.0" />
-    <PackageVersion Include="Verify.Xunit" Version="23.5.0" />
+    <PackageVersion Include="Verify.Xunit" Version="23.5.2" />
     <PackageVersion Include="xunit.runner.visualstudio" Version="2.5.7" />
     <PackageVersion Include="xunit" Version="2.7.0" />
   </ItemGroup>

README.md

@@ -36,6 +36,9 @@ Docfx is planned to continue as a community-driven project. We hope to produce f
 
 For more information, refer to [Getting Started](http://dotnet.github.io/docfx/tutorial/docfx_getting_started.html).
 
+> [!TIP]
+> Docfx publishes nightly builds to [GitHub Packages](https://github.com/orgs/dotnet/packages), this allows you to stay up-to-date with the latest developments in Docfx.
+
 ## Contributing
 
 Use [Discussions](https://github.com/dotnet/docfx/discussions) for questions and general discussions. 

docs/docs/markdown.md

@@ -50,6 +50,8 @@ Alternatively, set the `build.markdownEngineProperties.markdigExtensions` proper
 }
 ```
 
+The known extension names are listed in [MardownExtensions.Configure](https://github.com/xoofx/markdig/blob/master/src/Markdig/MarkdownExtensions.cs) method in the MarkDig project.
+
 > [!Note]
 > The custom configuration of extensions via the `build.markdownEngineProperties.markdigExtensions` property is not supported.
 

docs/reference/docfx-cli-reference/docfx-template.md

@@ -1,4 +1,4 @@
-# docfx build
+# docfx template
 
 ## Name
 

docs/reference/docfx-json-reference.md

@@ -10,9 +10,9 @@ The `docfx.json` file indicates that the directory is the root of a docfx projec
 }
 ```
 
-## Global properties 
+## Global properties
 
-### `rules`
+## `rules`
 
 Overrides default log message severity level. Key is the log code, supported values are `verbose`, `info`, `suggestion`, `warning`, `error`:
 
@@ -148,6 +148,7 @@ Templates are used to transform YAML files generated by `docfx` to human-readabl
   }
 }
 ```
+
 ```json
 {
   "build": {
@@ -166,7 +167,6 @@ The themes applied to the documentation. Theme is used to customize the styles g
 
 Theme is to provide general styles for all the generated pages. Files inside a theme will be generally copied to the output folder. A typical usage is, after YAML files are transformed to HTML pages, well-designed CSS style files in a Theme can then overwrite the default styles defined in template, e.g. `main.css`.
 
-
 ### `xref`
 
 Specifies the urls of xrefmap used by content files. Currently, it supports following scheme: http, https, file.
@@ -199,6 +199,22 @@ Sets the max parallelism. Setting 0 (default) is the same as setting to the coun
 
 Sets the parameters for the markdown engine, value is a JSON object.
 
+### `customLinkResolver`
+
+Set the name of the `ICustomHrefGenerator` derived class.
+
+### `groups`
+
+Specifies the output folder of specified group name.
+
+```json
+"groups":
+  "v1": {
+    "dest": "output_dir_v1"
+  }
+}
+```
+
 ### `sitemap`
 
 Specifies the options for generating [sitemap.xml](https://www.sitemaps.org/protocol.html) file:
@@ -320,6 +336,12 @@ Specifies the output folder of the generated metadata files relative to `docfx.j
 
 If set to true, DocFX would not render triple-slash-comments in source code as markdown.
 
+### `references`
+
+Specify additinal assembly reference files.
+This settings is used when generating metadata from DLLs or source files.
+Solution or project file-based metadata generation does not use this property.
+
 ### `filter`
 
 Specifies the filter configuration file, please go to [How to filter out unwanted apis attributes](../tutorial/howto_filter_out_unwanted_apis_attributes.md) for more details.
@@ -332,6 +354,10 @@ Disables the default filter configuration file.
 
 Disables generation of view source links.
 
+### `codeSourceBasePath`
+
+Specify the base directory that is used to resolve code source (e.g. `<code source="Example.cs">`).
+
 ### `properties`
 
 Specifies an optional set of MSBuild properties used when interpreting project files. These are the same properties that are passed to msbuild via the `/property:name=value` command line argument.
@@ -372,7 +398,7 @@ Specifies how member pages are organized:
 
 When enabled, continues documentation generation in case of compilation errors.
 
-### `EnumSortOrder`
+### `enumSortOrder`
 
 Specifies how enum members are sorted:
 

src/Docfx.App/Config/BuildJsonConfig.cs

@@ -202,14 +202,13 @@ internal class BuildJsonConfig
     public string CustomLinkResolver { get; set; }
 
     /// <summary>
-    /// Define groups.
+    /// Specifies the output folder of specified group name.
     /// </summary>
     /// <example>
     /// <code>
     /// groups:{
     ///   "v1": {
-    ///     "dest": "v1",
-    ///     "extraMetadata01": {}
+    ///     "dest": "output_dir_v1"
     ///   }
     /// }
     /// </code>

src/Docfx.App/PdfBuilder.cs

@@ -291,7 +291,7 @@ await Parallel.ForEachAsync(pages, async (item, _) =>
             if (outline.pdfTocPage)
             {
                 var href = $"/_pdftoc{outlineUrl.AbsolutePath}";
-                yield return (new(outlineUrl, href), new() { href = href, pdfPrintBackground = outline.pdfPrintBackground  });
+                yield return (new(outlineUrl, href), new() { href = href, pdfPrintBackground = outline.pdfPrintBackground });
             }
 
             if (!string.IsNullOrEmpty(outline.href))
@@ -325,6 +325,9 @@ async Task MergePdf()
                     // Refresh TOC page numbers
                     updatePageNumbers(pageNumbers);
                     bytes = await printPdf(outline, url);
+
+                    if (bytes == null)
+                        continue;
                 }
 
                 using var document = PdfDocument.Open(bytes);

src/Docfx.Build.SchemaDriven/Validators/SchemaValidator.cs

@@ -11,6 +11,12 @@ public class SchemaValidator
 {
     private readonly JsonSchema _schema;
 
+    private static readonly EvaluationOptions DefaultOptions = new EvaluationOptions
+    {
+        ValidateAgainstMetaSchema = false,
+        OutputFormat = OutputFormat.List,
+    };
+
     static SchemaValidator()
     {
         SchemaRegistry.Global.Register(new("http://dotnet.github.io/docfx/schemas/v1.0/schema.json#"), MetaSchemas.Draft7);
@@ -25,11 +31,7 @@ public SchemaValidator(string json)
     public void Validate(object obj)
     {
         var json = JsonSerializer.Serialize(obj);
-        var result = _schema.Evaluate(JsonDocument.Parse(json), new EvaluationOptions
-        {
-            ValidateAgainstMetaSchema = false,
-            OutputFormat = OutputFormat.List,
-        });
+        var result = _schema.Evaluate(JsonDocument.Parse(json), DefaultOptions);
 
         if (result.IsValid)
             return;

src/Docfx.Build/HostServiceCreator.cs

@@ -63,8 +63,12 @@ public virtual (FileModel model, bool valid) Load(
             {
                 if (e is not DocumentException)
                 {
+                    var message = e is ArgumentException or NullReferenceException
+                        ? e.ToString()
+                        : e.Message;
+
                     Logger.LogError(
-                        $"Unable to load file '{file.File}' via processor '{processor.Name}': {e.Message}",
+                        $"Unable to load file '{file.File}' via processor '{processor.Name}': {message}",
                         code: ErrorCodes.Build.InvalidInputFile);
                 }
                 return (null, false);

src/Docfx.Dotnet/Filters/ConfigFilterRuleItemUnion.cs

@@ -54,7 +54,10 @@ public ConfigFilterRuleItem Rule
             }
 
             // If kind is not specified for exclude. Set `ExtendedSymbolKind.Type` as default kind.
-            Exclude.Kind ??= ExtendedSymbolKind.Type | ExtendedSymbolKind.Member;
+            if (Exclude != null)
+            {
+                Exclude.Kind ??= ExtendedSymbolKind.Type | ExtendedSymbolKind.Member;
+            }
 
             return Exclude;
         }

src/Docfx.Dotnet/MetadataJsonConfig.cs

@@ -118,10 +118,11 @@ internal class MetadataJsonItemConfig
     [JsonPropertyName("shouldSkipMarkup")]
     public bool? ShouldSkipMarkup { get; set; }
 
-    [JsonProperty("raw")]
-    [JsonPropertyName("raw")]
-    public bool? Raw { get; set; }
-
+    /// <summary>
+    /// Specify additinal assembly reference files.
+    /// This settings is used when generating metadata from DLLs or source files.
+    /// Solution or project file-based metadata generation does not use this property.
+    /// </summary>
     [JsonProperty("references")]
     [JsonPropertyName("references")]
     public FileMapping References { get; set; }

templates/common/ManagedReference.common.js

@@ -261,4 +261,9 @@ function handleItem(vm, gitContribute, gitUrlPattern) {
 
     return array;
   }
+  if(vm.syntax.typeParameters) {
+    vm.syntax.typeParameters.forEach(item => {
+      item.description = item.description || "";
+    });
+  }
 }