-
Notifications
You must be signed in to change notification settings - Fork 23
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add usage samples for client API; Improve other doc pages to prep for…
… 9.0.0 release (#89)
- Loading branch information
1 parent
1625684
commit d2723c4
Showing
15 changed files
with
765 additions
and
209 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,158 @@ | ||
| # Copyright (c) Microsoft Corporation. | ||
| # Licensed under the MIT license. | ||
|
|
||
| # This script is used to add links to API documentation for manually authored Markdown files. | ||
| # It attempts to be as cautious as possible to avoid mis-linking an unrelated work to a C# class/API/etc. | ||
| # It should be run whenever you edit a manually authored Markdown file. | ||
| $regex = '\(.*\)' | ||
|
|
||
| # Files to search | ||
| $scriptDir = Split-Path $script:MyInvocation.MyCommand.Path | ||
| $docPath = [System.IO.Path]::Join($scriptDir, "docs") | ||
| $userDocs = Get-ChildItem -Path $docPath -filter "*.md" | ||
| $apiDocs = Get-ChildItem -Path $docPath -filter "Microsoft-FactoryOrchestrator-Core-TaskList*.md" -Recurse | ||
| $apiDocs += Get-ChildItem -Path $docPath -filter "Microsoft-FactoryOrchestrator-Core-TaskBase*.md" -Recurse | ||
| $apiDocs += Get-ChildItem -Path $docPath -filter "Microsoft-FactoryOrchestrator-Core-UWPTask.md" -Recurse | ||
| $apiDocs += Get-ChildItem -Path $docPath -filter "Microsoft-FactoryOrchestrator-Core-ExecutableTask.md" -Recurse | ||
| $apiDocs += Get-ChildItem -Path $docPath -filter "Microsoft-FactoryOrchestrator-Core-PowerShellTask.md" -Recurse | ||
| $apiDocs += Get-ChildItem -Path $docPath -filter "Microsoft-FactoryOrchestrator-Core-ExternalTask.md" -Recurse | ||
| $apiDocs += Get-ChildItem -Path $docPath -filter "Microsoft-FactoryOrchestrator-Core-TaskRun*.md" -Recurse | ||
| $apiDocs += Get-ChildItem -Path $docPath -filter "Microsoft-FactoryOrchestrator-Client-FactoryOrchestratorClient-*.md" -Recurse | ||
| $apiDocs += Get-ChildItem -Path $docPath -filter "Microsoft-FactoryOrchestrator-Client-ServerPoller-*.md" -Recurse | ||
| $apiDocs = $apiDocs | Sort-Object -Descending | ||
| $apiNames = @{} | ||
|
|
||
| # Ignore these words in .md even though they map to APIs, as they are used in multiple classes or are vague words. | ||
| $dupNames = @("Equals", "Name", "Guid", "ToString", "IsRunningOrPending", "Path", "Tasks", "Connect", "Status", "IpAddress", "EnumerateFiles", "EnumerateDirectories") | ||
| foreach ($doc in $apiDocs) | ||
| { | ||
| $name = $($doc.BaseName) | ||
|
|
||
| $regex = '\(.*\)' | ||
| $name = $name -replace $regex, '' | ||
|
|
||
| $name = $name.Split('-') | Select-Object -Last 1 | ||
| Write-Verbose "$name from $($doc.BaseName)" | ||
|
|
||
| if (-not $apiNames.ContainsKey($name)) | ||
| { | ||
| if (-not $dupNames.Contains($name)) | ||
| { | ||
| # Change file path to html path | ||
| $path = $($doc.FullName).Replace($docPath, "..").Replace('\','/').Replace('(', '%28').Replace(')', '%29').Replace('.md', '/') | ||
| $apiNames.add($name, $path) | ||
| Write-Verbose "Added $name to $path" | ||
| } | ||
| } | ||
| else | ||
| { | ||
| # if a name is in two different classes, dont link it as we might link the wrong one | ||
| Write-Verbose "Duplicate $name" | ||
|
|
||
| if (-not $dupNames.Contains($name)) | ||
| { | ||
| $dupNames += $name | ||
| } | ||
|
|
||
| if (-not ($apiNames[$name] -like "*()")) | ||
| { | ||
| $apiNames.remove($name) | ||
| Write-Warning "Possible confusion with $name" | ||
| } | ||
| } | ||
| } | ||
|
|
||
| # Add links until no more changes are found | ||
| $changeMade = $true | ||
| while ($changeMade -eq $true) | ||
| { | ||
| $changeMade = $false | ||
|
|
||
| foreach ($doc in $userDocs) | ||
| { | ||
| Write-Verbose "Checking $doc" | ||
| $content = Get-Content $doc | ||
| $edited = @() | ||
| $incode = $false | ||
| foreach ($line in $content) | ||
| { | ||
| $newline = $null | ||
| if ($line.Contains('```')) | ||
| { | ||
| # sadly I didn't find a way to add links to code snippets :( | ||
| $incode = -not $incode | ||
| } | ||
|
|
||
| if (-not $incode) | ||
| { | ||
| # Split line into words and words into sections | ||
| $words = $line.Split(' ') | ||
| $sections = $words.Split('.') | ||
| $sections = $sections.Split('(') | ||
| $sections = $sections.Split(',') | ||
| foreach ($section in $sections) | ||
| { | ||
| $section = $section.Replace(')', '') | ||
| $section = $section.Replace(';', '') | ||
| if ([System.Char]::IsUpper($section[0])) | ||
| { | ||
| if ($apiNames.ContainsKey($section)) | ||
| { | ||
| $index = $line.IndexOf($section) | ||
|
|
||
| # Don't add a link if it's already a link :) | ||
| while ($line[$index-1] -eq '[') | ||
| { | ||
| $index = $line.IndexOf($section, $index+1) | ||
| if ($index -eq -1) | ||
| { | ||
| break | ||
| } | ||
| } | ||
|
|
||
| if ($index -eq -1) | ||
| { | ||
| continue | ||
| } | ||
|
|
||
| # Ensure we are at the start of a new word, not in the middle of one. | ||
| while (($line[$index-1] -ne ' ') -and ($line[$index-1] -ne '(') -and ($line[$index-1] -ne '.')) | ||
| { | ||
| $index = $line.IndexOf($section, $index+1) | ||
| if ($index -eq -1) | ||
| { | ||
| break | ||
| } | ||
|
|
||
| } | ||
|
|
||
| if ($index -eq -1) | ||
| { | ||
| continue | ||
| } | ||
|
|
||
| # All checks are passed! Add the link! | ||
| Write-Host "found $section at $index ($($line.Substring($index, $section.Length)))" | ||
| Write-Host " $line" | ||
| Write-Host "" | ||
| Write-Host " $section maps to $($apiNames[$section])" | ||
| $newline = $line.Substring(0, $index) + "[$section]($($apiNames[$section]))" + $line.Substring($index + $section.Length) | ||
| $changeMade = $true | ||
| } | ||
| } | ||
| } | ||
| } | ||
|
|
||
| if ($null -ne $newline) | ||
| { | ||
| $edited += $newline | ||
| } | ||
| else | ||
| { | ||
| $edited += $line | ||
| } | ||
| } | ||
|
|
||
| Out-File -FilePath $doc -InputObject $edited | ||
| } | ||
| } |
2 changes: 1 addition & 1 deletion
2
...hestrator-Client-FactoryOrchestratorClient-EnableLocalLoopbackForApp(string).md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
2 changes: 1 addition & 1 deletion
2
...hestrator-Core-IFactoryOrchestratorService-EnableLocalLoopbackForApp(string).md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.