Skip to content

Commit

Permalink
feat: Microsoft.DocAsCode.* -> Docfx.* (#8943)
Browse files Browse the repository at this point in the history
yufeih authored Jul 12, 2023

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
1 parent fc7f48d commit a6d356c
Showing 999 changed files with 2,294 additions and 2,297 deletions.
1 change: 1 addition & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -63,6 +63,7 @@ jobs:

- uses: ./.github/actions/build

- run: dotnet build -c Release samples/extensions/build
- run: dotnet test -c Release -f net7.0 --no-build --filter Stage=Snapshot
working-directory: test/docfx.Snapshot.Tests
env:
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -9,7 +9,7 @@ _site
_site_pdf
docs/api
samples/**/api
src/Microsoft.DocAsCode.App/templates
src/Docfx.App/templates

*.user
*.log
84 changes: 42 additions & 42 deletions docfx.sln

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions docs/codesnippet/Rtf/Hyperlink/RtfDocumentProcessor.cs
Original file line number Diff line number Diff line change
@@ -12,8 +12,8 @@ namespace RtfDocumentProcessors
using System.Web;
using System.Xml.Linq;

using Microsoft.DocAsCode.Plugins;
using Microsoft.DocAsCode.Utility;
using Docfx.Plugins;
using Docfx.Utility;

[Export(typeof(IDocumentProcessor))]
public class RtfDocumentProcessor : IDocumentProcessor
2 changes: 1 addition & 1 deletion docs/codesnippet/Rtf/RtfBuildStep.cs
Original file line number Diff line number Diff line change
@@ -11,7 +11,7 @@ namespace RtfDocumentProcessors
using System.Threading.Tasks.Schedulers;

using MarkupConverter;
using Microsoft.DocAsCode.Plugins;
using Docfx.Plugins;

[Export(nameof(RtfDocumentProcessor), typeof(IDocumentBuildStep))]
public class RtfBuildStep : IDocumentBuildStep
4 changes: 2 additions & 2 deletions docs/codesnippet/Rtf/RtfDocumentProcessor.cs
Original file line number Diff line number Diff line change
@@ -9,8 +9,8 @@ namespace RtfDocumentProcessors
using System.Composition;
using System.IO;

using Microsoft.DocAsCode.Common;
using Microsoft.DocAsCode.Plugins;
using Docfx.Common;
using Docfx.Plugins;

[Export(typeof(IDocumentProcessor))]
public class RtfDocumentProcessor : IDocumentProcessor
4 changes: 2 additions & 2 deletions docs/docfx.json
Original file line number Diff line number Diff line change
@@ -4,8 +4,8 @@
"src": [
{
"files": [
"src/Microsoft.DocAsCode.App/*.csproj",
"src/Microsoft.DocAsCode.Dotnet/*.csproj"
"src/Docfx.App/*.csproj",
"src/Docfx.Dotnet/*.csproj"
],
"src": "../"
}
2 changes: 1 addition & 1 deletion docs/docs/basic-concepts.md
Original file line number Diff line number Diff line change
@@ -33,7 +33,7 @@ Static documentation pages are prepared using [Markdown](markdown.md) (slightly

Once the API documentation has been parsed from the source code, it is compiled along with the Markdown content into a set of HTML pages which can be published on a website. It is also possible to compile the final output into one or more PDFs for offline use.

Docfx is a command-line tool that can be invoked directly, or as a .NET Core CLI tool using the `dotnet` command, but it can also be invoked from source code using the `Docset.Build` method in the `Microsoft.DocAsCode` namespace. It is configured using a JSON configuration file, [`docfx.json`](../reference/docfx-json-reference.md) which has sections for different parts of the build process.
Docfx is a command-line tool that can be invoked directly, or as a .NET Core CLI tool using the `dotnet` command, but it can also be invoked from source code using the `Docset.Build` method in the `Docfx` namespace. It is configured using a JSON configuration file, [`docfx.json`](../reference/docfx-json-reference.md) which has sections for different parts of the build process.

## Consuming .NET projects

10 changes: 5 additions & 5 deletions docs/docs/dotnet-api-docs.md
Original file line number Diff line number Diff line change
@@ -27,8 +27,8 @@ Docfx generates .NET API docs in 2 stages:
1. The _metadata_ stage uses the `metadata` config to produce [.NET API YAML files](dotnet-yaml-format.md) at the `metadata.dest` directory.

> [!NOTE]
> The [`Docset.Build`](../api/Microsoft.DocAsCode.Docset.yml) method does not run the _metadata_ stage,
> invoke the [`DotnetApiCatalog.GenerateManagedReferenceYamlFiles`](../api/Microsoft.DocAsCode.Dotnet.DotnetApiCatalog.yml) method to run the _metadata_ stage before the _build_ stage.
> The [`Docset.Build`](../api/Docfx.Docset.yml) method does not run the _metadata_ stage,
> invoke the [`DotnetApiCatalog.GenerateManagedReferenceYamlFiles`](../api/Docfx.Dotnet.DotnetApiCatalog.yml) method to run the _metadata_ stage before the _build_ stage.
2. The _build_ stage transforms the generated .NET API YAML files specified in `build.content` config into HTML files.

@@ -148,7 +148,7 @@ To disable markdown parsing while processing XML tags, set `shouldSkipMarkup` to

## Filter APIs

Docfx shows only the public accessible types and methods callable from another assembly. It also has a set of [default filtering rules](https://github.com/dotnet/docfx/blob/main/src/Microsoft.DocAsCode.Metadata.ManagedReference.Common/Filters/defaultfilterconfig.yml) that excludes common API patterns based on attributes such as `[EditorBrowsableAttribute]`.
Docfx shows only the public accessible types and methods callable from another assembly. It also has a set of [default filtering rules](https://github.com/dotnet/docfx/blob/main/src/Docfx.Metadata.ManagedReference.Common/Filters/defaultfilterconfig.yml) that excludes common API patterns based on attributes such as `[EditorBrowsableAttribute]`.

To disable the default filtering rules, set the `disableDefaultFilter` property to `true`.

@@ -163,7 +163,7 @@ To use a custom filtering with code:
1. Use docfx .NET API generation as a NuGet library:

```xml
<PackageReference Include="Microsoft.DocAsCode.Dotnet" Version="2.62.0" />
<PackageReference Include="Docfx.Dotnet" Version="2.62.0" />
```

2. Configure the filter options:
@@ -181,7 +181,7 @@ var options = new DotnetApiOptions
await DotnetApiCatalog.GenerateManagedReferenceYamlFiles("docfx.json", options);
```

The filter callbacks takes an [`ISymbol`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.codeanalysis.isymbol?view=roslyn-dotnet) interface and produces an [`SymbolIncludeState`](../api/Microsoft.Docascode.Dotnet.SymbolIncludeState.yml) enum to choose between include the API, exclude the API or use the default filtering behavior.
The filter callbacks takes an [`ISymbol`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.codeanalysis.isymbol?view=roslyn-dotnet) interface and produces an [`SymbolIncludeState`](../api/Docfx.Dotnet.SymbolIncludeState.yml) enum to choose between include the API, exclude the API or use the default filtering behavior.

The callbacks are raised before applying the default rules but after processing type accessibility rules. Private types and members cannot be marked as include unless `includePrivateMembers` is true.

2 changes: 1 addition & 1 deletion docs/docs/markdown.md
Original file line number Diff line number Diff line change
@@ -11,7 +11,7 @@ To use a custom markdown extension:
1. Use docfx as a NuGet library:

```xml
<PackageReference Include="Microsoft.DocAsCode.App" Version="2.61.0" />
<PackageReference Include="Docfx.App" Version="2.70.0" />
```

2. Configure the markdig markdown pipeline:
4 changes: 2 additions & 2 deletions docs/extensions/packages.yml
Original file line number Diff line number Diff line change
@@ -11,7 +11,7 @@ items:
homepage: https://www.nuget.org/packages/rest.tagpage/
repository:
type: git
url: "https://github.com/dotnet/docfx/tree/master/plugins/Microsoft.DocAsCode.Build.TagLevelRestApi"
url: "https://github.com/dotnet/docfx/tree/master/plugins/Docfx.Build.TagLevelRestApi"
usage:
init: "nuget install rest.tagpage -OutputDirectory <output>"
command: "-t default,<output>/rest.tagpage.<version>/content"
@@ -23,7 +23,7 @@ items:
homepage: https://www.nuget.org/packages/rest.operationpage/
repository:
type: git
url: "https://github.com/dotnet/docfx/tree/master/plugins/Microsoft.DocAsCode.Build.OperationLevelRestApi"
url: "https://github.com/dotnet/docfx/tree/master/plugins/Docfx.Build.OperationLevelRestApi"
usage:
init: "nuget install rest.operationpage -OutputDirectory <output>"
command: "-t default,<output>/rest.operationpage.<version>/content"
6 changes: 3 additions & 3 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -75,16 +75,16 @@ jobs:
You can also use docfx as a NuGet library:
```xml
<PackageReference Include="Microsoft.DocAsCode.App" Version="2.60.0" />
<PackageReference Include="Docfx.App" Version="2.70.0" />
```

Then build a docset using:

```cs
await Microsoft.DocAsCode.Docset.Build("docfx.json");
await Docfx.Docset.Build("docfx.json");
```

See [API References](api/Microsoft.DocAsCode.yml) for additional APIs.
See [API References](api/Docfx.yml) for additional APIs.

## Next Steps

2 changes: 1 addition & 1 deletion docs/tutorial/advanced_support_hyperlink.md
Original file line number Diff line number Diff line change
@@ -63,7 +63,7 @@ Prepare
1. Open the rtf plug-in library project in `Visual Studio`.
2. Add nuget packages:
for plug-in: `Microsoft.DocAsCode.Utility`
for plug-in: `Docfx.Utility`
3. Add framework assembly reference:
`System.Core`, `System.Web`, `System.Xml.Linq`
4 changes: 2 additions & 2 deletions docs/tutorial/howto_add_a_customized_post_processor.md
Original file line number Diff line number Diff line change
@@ -11,9 +11,9 @@ In this topic, we will show how to add a customized post-processor.
* Add nuget packages:
* [`System.Collections.Immutable`](https://www.nuget.org/packages/System.Collections.Immutable/1.3.1) with version 1.3.1
* [`Microsoft.Composition`](https://www.nuget.org/packages/Microsoft.Composition/1.0.31) with version 1.0.31
* Add `Microsoft.DocAsCode.Plugins`
* Add `Docfx.Plugins`
If you are building DocFX from source code, add this reference to the project,
otherwise add the nuget package `Microsoft.DocAsCode.Plugins` with the same version as DocFX.
otherwise add the nuget package `Docfx.Plugins` with the same version as DocFX.

## Step1: Create a new class (MyProcessor.cs) with the following code:

Original file line number Diff line number Diff line change
@@ -17,7 +17,7 @@ Preparation
-----------
1. Create a new C# class library targeting `net6.0` or later.

2. Add NuGet package reference to `System.Composition`, `Microsoft.DocAsCode.Plugins` and `Microsoft.DocAsCode.Common`.
2. Add NuGet package reference to `System.Composition`, `Docfx.Plugins` and `Docfx.Common`.

4. Add a project for converting rtf to html:
Clone project [MarkupConverter](https://github.com/mmanela/MarkupConverter), and reference it.
@@ -57,7 +57,7 @@ Create a document processor
3. Load our rtf file by reading all text:
[!Code-csharp[Load](../codesnippet/Rtf/RtfDocumentProcessor.cs?name=Load)]

We use `Dictionary<string, object>` as the data model, similar to how [ConceptualDocumentProcessor](https://github.com/dotnet/docfx/blob/dev/src/Microsoft.DocAsCode.Build.ConceptualDocuments/ConceptualDocumentProcessor.cs)
We use `Dictionary<string, object>` as the data model, similar to how [ConceptualDocumentProcessor](https://github.com/dotnet/docfx/blob/dev/src/Docfx.Build.ConceptualDocuments/ConceptualDocumentProcessor.cs)
stores the content of markdown files.

4. Implement `Save` method as follows:
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
<Project Sdk="Microsoft.NET.Sdk">
<ItemGroup>
<ProjectReference Include="..\..\src\Docfx.Build.Common\Docfx.Build.Common.csproj" />
<ProjectReference Include="..\..\src\Docfx.Common\Docfx.Common.csproj" />
<ProjectReference Include="..\..\src\Docfx.DataContracts.RestApi\Docfx.DataContracts.RestApi.csproj" />
<ProjectReference Include="..\..\src\Docfx.Plugins\Docfx.Plugins.csproj" />
</ItemGroup>
</Project>
Original file line number Diff line number Diff line change
@@ -4,13 +4,13 @@
using System.Collections.Immutable;
using System.Composition;

using Microsoft.DocAsCode.Build.Common;
using Microsoft.DocAsCode.Common;
using Microsoft.DocAsCode.DataContracts.Common;
using Microsoft.DocAsCode.DataContracts.RestApi;
using Microsoft.DocAsCode.Plugins;
using Docfx.Build.Common;
using Docfx.Common;
using Docfx.DataContracts.Common;
using Docfx.DataContracts.RestApi;
using Docfx.Plugins;

namespace Microsoft.DocAsCode.Build.OperationLevelRestApi;
namespace Docfx.Build.OperationLevelRestApi;

[Export("RestApiDocumentProcessor", typeof(IDocumentBuildStep))]
public class SplitRestApiToOperationLevel : BaseDocumentBuildStep
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
<Project Sdk="Microsoft.NET.Sdk">
<ItemGroup>
<ProjectReference Include="..\..\src\Docfx.Build.Common\Docfx.Build.Common.csproj" />
<ProjectReference Include="..\..\src\Docfx.Common\Docfx.Common.csproj" />
<ProjectReference Include="..\..\src\Docfx.DataContracts.RestApi\Docfx.DataContracts.RestApi.csproj" />
<ProjectReference Include="..\..\src\Docfx.Plugins\Docfx.Plugins.csproj" />
</ItemGroup>
</Project>
Original file line number Diff line number Diff line change
@@ -4,13 +4,13 @@
using System.Collections.Immutable;
using System.Composition;

using Microsoft.DocAsCode.Build.Common;
using Microsoft.DocAsCode.Common;
using Microsoft.DocAsCode.DataContracts.Common;
using Microsoft.DocAsCode.DataContracts.RestApi;
using Microsoft.DocAsCode.Plugins;
using Docfx.Build.Common;
using Docfx.Common;
using Docfx.DataContracts.Common;
using Docfx.DataContracts.RestApi;
using Docfx.Plugins;

namespace Microsoft.DocAsCode.Build.TagLevelRestApi;
namespace Docfx.Build.TagLevelRestApi;

[Export("RestApiDocumentProcessor", typeof(IDocumentBuildStep))]
public class SplitRestApiToTagLevel : BaseDocumentBuildStep

This file was deleted.

This file was deleted.

3 changes: 1 addition & 2 deletions publish.yml
Original file line number Diff line number Diff line change
@@ -81,8 +81,7 @@ jobs:
artifact: nuget

- powershell: |
dotnet nuget push $(Pipeline.Workspace)\nuget\Microsoft.DocAsCode.*.nupkg --api-key $env:NUGET_KEY --skip-duplicate --source https://nuget.org
dotnet nuget push $(Pipeline.Workspace)\nuget\docfx.*.nupkg --api-key $env:NUGET_KEY --skip-duplicate --source https://nuget.org
dotnet nuget push $(Pipeline.Workspace)\nuget\*.nupkg --api-key $env:NUGET_KEY --skip-duplicate --source https://nuget.org
displayName: dotnet nuget push
env:
NUGET_KEY: $(NUGET_KEY)
4 changes: 2 additions & 2 deletions samples/extensions/README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Customize docfx with extensions

This sample shows how to use docfx as a library. It uses the `Microsoft.DocAsCode.App` package to build the project instead of using the global `docfx` commandline tool. To build the project, run the following command in this directory:
This sample shows how to use docfx as a library. It uses the `Docfx.App` package to build the project instead of using the global `docfx` commandline tool. To build the project, run the following command in this directory:

```bash
dotnet run --project build
```

This sample creates a standalone executable to integrate with the `Microsoft.DocAsCode.App` package and extensions. You can also use [dotnet script](https://github.com/dotnet-script/dotnet-script#installing) or other interactive scripting tools for integration.
This sample creates a standalone executable to integrate with the `Docfx.App` package and extensions. You can also use [dotnet script](https://github.com/dotnet-script/dotnet-script#installing) or other interactive scripting tools for integration.
4 changes: 2 additions & 2 deletions samples/extensions/build/Program.cs
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
using Microsoft.DocAsCode;
using Microsoft.DocAsCode.Dotnet;
using Docfx;
using Docfx.Dotnet;
using Markdig;

await DotnetApiCatalog.GenerateManagedReferenceYamlFiles("docfx.json", new()
4 changes: 2 additions & 2 deletions samples/extensions/build/build.csproj
Original file line number Diff line number Diff line change
@@ -8,13 +8,13 @@
</PropertyGroup>

<ItemGroup>
<ProjectReference Include="..\..\..\src\Microsoft.DocAsCode.App\Microsoft.DocAsCode.App.csproj" />
<ProjectReference Include="..\..\..\src\Docfx.App\Docfx.App.csproj" />
</ItemGroup>

<!-- NOTE: Uncomment to use <PackageReference> for your own project. -->
<!--
<ItemGroup>
<PackageReference Include="Microsoft.DocAsCode.App" Version="2.60.2" />
<PackageReference Include="Docfx.App" Version="2.70.0" />
</ItemGroup>
-->

2 changes: 1 addition & 1 deletion samples/seed/articles/engineering_guidelines.md
Original file line number Diff line number Diff line change
@@ -73,7 +73,7 @@ Every project also needs a `project.json` and a matching `.xproj` file. This `pr
Solution need to contain solution folders that match the physical folder (`src`, `test`, `tools`, etc.).

### Assembly naming pattern
The general naming pattern is `Microsoft.DocAsCode.<area>.<subarea>`.
The general naming pattern is `Docfx.<area>.<subarea>`.

### Unit tests
We use *xUnit.net* for all unit testing.
Original file line number Diff line number Diff line change
@@ -5,7 +5,7 @@

#nullable enable

namespace Microsoft.DocAsCode;
namespace Docfx;

/// <summary>
/// Provides options to be used with <see cref="Docset.Build(string, BuildOptions)"/>.
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using Microsoft.DocAsCode.Common;
using Microsoft.DocAsCode.Plugins;
using Docfx.Common;
using Docfx.Plugins;

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

namespace Microsoft.DocAsCode;
namespace Docfx;

[Serializable]
internal class BuildJsonConfig
Original file line number Diff line number Diff line change
@@ -3,7 +3,7 @@

using Newtonsoft.Json;

namespace Microsoft.DocAsCode;
namespace Docfx;

[Serializable]
internal class ContentPairingInfo
Original file line number Diff line number Diff line change
@@ -3,7 +3,7 @@

using Newtonsoft.Json;

namespace Microsoft.DocAsCode;
namespace Docfx;

[Serializable]
[JsonConverter(typeof(FileMetadataPairsConverter))]
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using Microsoft.DocAsCode.Common;
using Docfx.Common;

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

namespace Microsoft.DocAsCode;
namespace Docfx;

internal class FileMetadataPairsConverter : JsonConverter
{
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using Microsoft.DocAsCode.Common;
using Microsoft.DocAsCode.Glob;
using Docfx.Common;
using Docfx.Glob;

namespace Microsoft.DocAsCode;
namespace Docfx;

[Serializable]
internal class FileMetadataPairsItem
Loading

0 comments on commit a6d356c

Please sign in to comment.