Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: New extensibility model based on libraries #8306

Merged
merged 19 commits into from
Dec 22, 2022
Merged

Conversation

yufeih
Copy link
Contributor

@yufeih yufeih commented Dec 21, 2022

This is a new extensibility model by shipping docfx as a library. It changes the extensibility model from runtime to build time:

  • Microsoft.DocAsCode is a new library package with public APIs to build a project with the exact same behavior as executing the docfx CLI.
  • The docfx package is a thin command line wrapper around Microsoft.DocAsCode.
  • To enable extensibility, create a new EXE project and add Microsoft.DocAsCode package
  • It should also work seamlessly with more script-oriented build systems like dotnet-script or cake.
  • Extensions like memberpage are shipped as ordinary NuGet libraries, to use an extension, add it to the project using <PackageReference>.
  • More extensibility options like markdown extensions, template extensions can be exposed through Microsoft.DocAsCode with additional APIs for customization.

See samples/extensions folder on an EXE project sample.

This approach solves the problems of sharing+consuming extensions and assembly loading issues with the plugin approach.
Loading plugins dynamically was removed with this change.

NOTE: This PR makes memberpage C# code work, but the memberpage templates are not yet solved.

The initial APIs exposed by this PR are:

namespace Microsoft.DocAsCode;

public class Docset
{
    public static Task Build(string configPath);
}

cc @vicancy

@yufeih yufeih added the new-feature Makes the pull request to appear in "New Features" section of the next release note label Dec 21, 2022
@yufeih yufeih added this to the Working Set milestone Dec 21, 2022
@yufeih yufeih self-assigned this Dec 21, 2022
Copy link
Contributor

@vicancy vicancy left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks awesome! Some little comments on the API surface

src/Microsoft.DocAsCode.App/DocfxProject.cs Outdated Show resolved Hide resolved
src/Microsoft.DocAsCode.App/DocfxProject.cs Outdated Show resolved Hide resolved
@codecov
Copy link

codecov bot commented Dec 21, 2022

Codecov Report

Base: 72.79% // Head: 73.25% // Increases project coverage by +0.46% 🎉

Coverage data is based on head (fde1265) compared to base (d828308).
Patch coverage: 26.12% of modified lines in pull request are covered.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #8306      +/-   ##
==========================================
+ Coverage   72.79%   73.25%   +0.46%     
==========================================
  Files         953      955       +2     
  Lines       38680    38627      -53     
  Branches     7191     7186       -5     
==========================================
+ Hits        28158    28298     +140     
+ Misses       8387     8204     -183     
+ Partials     2135     2125      -10     
Impacted Files Coverage Δ
src/Microsoft.DocAsCode/Config/BuildJsonConfig.cs 90.19% <ø> (ø)
...c/Microsoft.DocAsCode/Config/ContentPairingInfo.cs 0.00% <ø> (ø)
src/Microsoft.DocAsCode/Config/FileItems.cs 71.42% <ø> (ø)
src/Microsoft.DocAsCode/Config/FileMapping.cs 73.33% <ø> (ø)
...Microsoft.DocAsCode/Config/FileMappingConverter.cs 83.33% <ø> (ø)
src/Microsoft.DocAsCode/Config/FileMappingItem.cs 82.75% <ø> (ø)
...rc/Microsoft.DocAsCode/Config/FileMetadataPairs.cs 66.66% <ø> (ø)
...oft.DocAsCode/Config/FileMetadataPairsConverter.cs 72.22% <ø> (ø)
...icrosoft.DocAsCode/Config/FileMetadataPairsItem.cs 100.00% <ø> (ø)
src/Microsoft.DocAsCode/Config/FileModelParser.cs 20.00% <ø> (ø)
... and 43 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

@yufeih yufeih enabled auto-merge (squash) December 22, 2022 04:12
@yufeih yufeih disabled auto-merge December 22, 2022 04:12
@yufeih yufeih merged commit ab685f8 into main Dec 22, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
new-feature Makes the pull request to appear in "New Features" section of the next release note
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants