Skip to content

Commit

Permalink
BREAKING CHANGE: retire xref service (dotnet#8595)
Browse files Browse the repository at this point in the history
  • Loading branch information
@yufeih @p-kostov
yufeih authored and p-kostov committed Jun 28, 2024
1 parent 42bb6ba commit b16027a
Show file tree
Hide file tree
Showing 10 changed files with 4 additions and 378 deletions.
33 changes: 0 additions & 33 deletions docs/tutorial/docfx.exe_user_manual.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -226,7 +226,6 @@ fileMetadataFiles | Specify a list of JSON file path containing fileMetad
template | The templates applied to each file in the documentation. It can be a string or an array. The latter ones will override the former ones if the name of the file inside the template collides. If omitted, embedded `default` template will be used.
theme | The themes applied to the documentation. Theme is used to customize the styles generated by `template`. It can be a string or an array. The latter ones will override the former ones if the name of the file inside the template collides. If omitted, no theme will be applied, the default theme inside the template will be used.
xref | Specifies the urls of xrefmap used by content files. Currently, it supports following scheme: http, https, ftp, file, embedded.
xrefService | Specifies the url patterns of xref service. Please read **Section3.2.4** for detail.
exportRawModel | If set to true, data model to run template script will be extracted in `.raw.json` extension.
rawModelOutputFolder | Specify the output folder for the raw model. If not set, the raw model will be generated to the same folder as the output documentation.
exportViewModel | If set to true, data model to apply template will be extracted in `.view.json` extension.
Expand Down Expand Up @@ -425,38 +424,6 @@ Note that, metadata set in command line will merge with metadata set in `docfx.j

Given multiple metadata files, the behavior would be **undetermined**, if same key is set in these files.

#### 3.2.4 Xref service url pattern

Xref service url pattern will exact url by following steps:

1. Replace environment variables.

* Syntax: `{%variableName%}`
* Process: load variable value from enviroment variables, replace the source content.
2. Extract post pipelines.

* Syntax: `|> pipelineName parameter1 parameter2 ...`
* Process: load pipeline, and extract parameters, remove from url.
* Current pipeline only contains: `removeHost`, `addQueryString`, pluggable pipeline will be add later.
3. Runtime replace variables.

* Syntax: `{varName}`
* Process: replace the source content to the value of variable (uri data encoded).

e.g.:\
Environment variables: test = hello\
Available Pipeline: removeHost\
Variable: uid = testuid1\
Url pattern: `http://{%test%}.contoso.com/?uid={uid}|> removeHost`

It will run as following steps:

1. Replace environment variables, `http://hello.contoso.com/?uid={uid}|> removeHost`.
2. Extract post pipelines, `http://hello.contoso.com/?uid={uid}`, and append a post pipeline `removeHost`.
3. Runtime replace variables, `http://hello.contoso.com/?uid=testuid`.
4. Send request to `http://hello.contoso.com/?uid=testuid`, and get response from site.
5. Run post pipeline `removeHost`.

#### 3.2.5 SitemapOptions

The SitemapOptions is to configure the values for generating [sitemap.xml](https://www.sitemaps.org/protocol.html) file.
Expand Down
15 changes: 0 additions & 15 deletions docs/tutorial/links_and_cross_references.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -290,21 +290,6 @@ The value of `xref` could be a string or a list of strings that contain the path
> the website together with topic files so that others can directly use its url in `docfx.json` instead of downloading it to
> local.

### Cross reference services

Cross reference services are hosted services that can be queried for cross reference information. When DocFX generates the metadata for your project, it will perform cross reference lookups against the service.

To use a cross reference service, add a `xrefservice` config to the `build` section of `docfx.json`:

```json
{
"build": {
"xrefService": [ "<url_to_xrefservice>" ],
...
}
}
```

## Advanced: more options for cross reference

You can create a cross link with following options:
Expand Down
3 changes: 0 additions & 3 deletions src/Microsoft.DocAsCode.App/Config/BuildJsonConfig.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,6 @@ internal class BuildJsonConfig
[JsonProperty("xref")]
public ListWithStringFallback XRefMaps { get; set; }

[JsonProperty("xrefService")]
public ListWithStringFallback XRefServiceUrls { get; set; }

[JsonProperty("dest")]
public string Destination { get; set; }

Expand Down
4 changes: 0 additions & 4 deletions src/Microsoft.DocAsCode.App/Helpers/DocumentBuilderWrapper.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -148,10 +148,6 @@ private static List<DocumentBuildParameters> ConfigToParameter(BuildJsonConfig c
{
parameters.XRefMaps = config.XRefMaps.ToImmutableArray();
}
if (config.XRefServiceUrls != null)
{
parameters.XRefServiceUrls = config.XRefServiceUrls.ToImmutableArray();
}

string outputFolderForDebugFiles = null;
if (!string.IsNullOrEmpty(config.OutputFolderForDebugFiles))
Expand Down
72 changes: 4 additions & 68 deletions src/Microsoft.DocAsCode.Build.Engine/DocumentBuildContext.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,16 +18,15 @@ public sealed class DocumentBuildContext : IDocumentBuildContext
private readonly ConcurrentDictionary<string, TocInfo> _tableOfContents = new(FilePathComparer.OSPlatformSensitiveStringComparer);
private readonly Task<IXRefContainerReader> _reader;
private ImmutableArray<string> _xrefMapUrls { get; }
private ImmutableArray<string> _xrefServiceUrls { get; }

public DocumentBuildContext(string buildOutputFolder)
: this(buildOutputFolder, Enumerable.Empty<FileAndType>(), ImmutableArray<string>.Empty, ImmutableArray<string>.Empty, 1, Directory.GetCurrentDirectory(), string.Empty, null, null) { }

public DocumentBuildContext(string buildOutputFolder, IEnumerable<FileAndType> allSourceFiles, ImmutableArray<string> externalReferencePackages, ImmutableArray<string> xrefMaps, int maxParallelism, string baseFolder, string versionName, ApplyTemplateSettings applyTemplateSetting, string rootTocPath)
: this(buildOutputFolder, allSourceFiles, externalReferencePackages, xrefMaps, maxParallelism, baseFolder, versionName, applyTemplateSetting, rootTocPath, null, ImmutableArray<string>.Empty) { }
: this(buildOutputFolder, allSourceFiles, externalReferencePackages, xrefMaps, maxParallelism, baseFolder, versionName, applyTemplateSetting, rootTocPath, null) { }

public DocumentBuildContext(string buildOutputFolder, IEnumerable<FileAndType> allSourceFiles, ImmutableArray<string> externalReferencePackages, ImmutableArray<string> xrefMaps, int maxParallelism, string baseFolder, string versionName, ApplyTemplateSettings applyTemplateSetting, string rootTocPath, string versionFolder, ImmutableArray<string> xrefServiceUrls)
: this(buildOutputFolder, allSourceFiles, externalReferencePackages, xrefMaps, maxParallelism, baseFolder, versionName, applyTemplateSetting, rootTocPath, null, ImmutableArray<string>.Empty, null, null) { }
public DocumentBuildContext(string buildOutputFolder, IEnumerable<FileAndType> allSourceFiles, ImmutableArray<string> externalReferencePackages, ImmutableArray<string> xrefMaps, int maxParallelism, string baseFolder, string versionName, ApplyTemplateSettings applyTemplateSetting, string rootTocPath, string versionFolder)
: this(buildOutputFolder, allSourceFiles, externalReferencePackages, xrefMaps, maxParallelism, baseFolder, versionName, applyTemplateSetting, rootTocPath, null, null, null) { }

public DocumentBuildContext(DocumentBuildParameters parameters)
{
Expand All @@ -37,7 +36,6 @@ public DocumentBuildContext(DocumentBuildParameters parameters)
HrefGenerator = parameters.ApplyTemplateSettings?.HrefGenerator;
AllSourceFiles = GetAllSourceFiles(parameters.Files.EnumerateFiles());
_xrefMapUrls = parameters.XRefMaps;
_xrefServiceUrls = parameters.XRefServiceUrls;
GroupInfo = parameters.GroupInfo;
XRefTags = parameters.XRefTags;
MaxParallelism = parameters.MaxParallelism;
Expand Down Expand Up @@ -78,7 +76,6 @@ public DocumentBuildContext(
ApplyTemplateSettings applyTemplateSetting,
string rootTocPath,
string versionFolder,
ImmutableArray<string> xrefServiceUrls,
GroupInfo groupInfo,
List<string> xrefTags)
{
Expand All @@ -89,7 +86,6 @@ public DocumentBuildContext(
AllSourceFiles = GetAllSourceFiles(allSourceFiles);
ExternalReferencePackages = externalReferencePackages;
_xrefMapUrls = xrefMaps;
_xrefServiceUrls = xrefServiceUrls;
GroupInfo = groupInfo;
XRefTags = xrefTags;
MaxParallelism = maxParallelism;
Expand Down Expand Up @@ -204,7 +200,7 @@ private void ResolveExternalXRefSpecForSpecs()
}
}

public async Task ResolveExternalXRefSpecForNoneSpecsAsync()
public void ResolveExternalXRefSpecForNoneSpecsAsync()
{
// remove internal xref.
var uidList =
Expand All @@ -226,10 +222,6 @@ from spec in ExternalXRefSpec.Values
{
uidList = ResolveByExternalReferencePackages(uidList, ExternalXRefSpec);
}
if (uidList.Count > 0)
{
uidList = await ResolveByXRefServiceAsync(uidList, ExternalXRefSpec);
}

Logger.LogVerbose($"{uidList.Count} uids are unresolved.");

Expand Down Expand Up @@ -268,56 +260,6 @@ private List<string> ResolveByExternalReferencePackages(List<string> uidList, Co
return list;
}

private async Task<List<string>> ResolveByXRefServiceAsync(List<string> uidList, ConcurrentDictionary<string, XRefSpec> externalXRefSpec)
{
if (_xrefServiceUrls == null || _xrefServiceUrls.Length == 0)
{
return uidList;
}

var unresolvedUidList = await new XrefServiceResolver(_xrefServiceUrls, MaxHttpParallelism).ResolveAsync(uidList, externalXRefSpec);
Logger.LogInfo($"{uidList.Count - unresolvedUidList.Count} uids found in {_xrefServiceUrls.Length} xrefservice(s).");
return unresolvedUidList;
}

internal async Task<IList<XRefSpec>> QueryByHttpRequestAsync(HttpClient client, string requestUrl, string uid)
{
string url = requestUrl.Replace("{uid}", Uri.EscapeDataString(uid));
try
{
var data = await client.GetStreamAsync(url);
using var sr = new StreamReader(data);
var xsList = JsonUtility.Deserialize<List<Dictionary<string, object>>>(sr);
return xsList.ConvertAll(item =>
{
var spec = new XRefSpec();
foreach (var pair in item)
{
if (pair.Value is string s)
{
spec[pair.Key] = s;
}
}
return spec;
});
}
catch (HttpRequestException e)
{
Logger.LogWarning($"Error occurs when resolve {uid} from {requestUrl}.{e.InnerException.Message}");
return null;
}
catch (Newtonsoft.Json.JsonReaderException e)
{
Logger.LogWarning($"Response from {requestUrl} is not in valid JSON format.{e.Message}");
return null;
}
catch (Exception e)
{
Logger.LogWarning($"Error occurs when resolve {uid} from {requestUrl}.{e.Message}");
return null;
}
}

private List<string> ResolveByXRefMaps(List<string> uidList, ConcurrentDictionary<string, XRefSpec> externalXRefSpec)
{
if (_reader == null)
Expand Down Expand Up @@ -561,12 +503,6 @@ public XRefSpec GetXrefSpec(string uid)
}
}

var uidList = ResolveByXRefServiceAsync(new List<string> { uid }, ExternalXRefSpec).Result;
if (uidList.Count == 0)
{
return ExternalXRefSpec[uid];
}

UnknownUids.TryAdd(uid, null);
return null;
}
Expand Down
2 changes: 0 additions & 2 deletions src/Microsoft.DocAsCode.Build.Engine/DocumentBuildParameters.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,6 @@ public sealed class DocumentBuildParameters : IBuildParameters

public ImmutableArray<string> XRefMaps { get; set; } = ImmutableArray<string>.Empty;

public ImmutableArray<string> XRefServiceUrls { get; set; } = ImmutableArray<string>.Empty;

public ImmutableDictionary<string, object> Metadata { get; set; } = ImmutableDictionary<string, object>.Empty;

public FileMetadata FileMetadata { get; set; }
Expand Down
Loading

0 comments on commit b16027a

Please sign in to comment.