Skip to content

docs: Add how to use docfx nightly version #10394

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Nov 20, 2024
Merged

docs: Add how to use docfx nightly version #10394

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,53 @@ await Docfx.Docset.Build("docfx.json");

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

## How to use prerelease version of docfx

Docfx publishes nightly builds to [GitHub Packages](https://github.com/dotnet/docfx/pkgs/nuget/docfx).
If you want to use prerelease version, you can install package with following steps.

### Prerequisite

1. Install [GitHub CLI](https://github.com/cli/cli) command.
2. Install PowerShell 7.x or later.

### Steps

1. Open PowerShell on working directory.

2. Login to GitHub with additional scope request

```pwsh
gh auth login --scopes "read:packages" --host github.com
```

3. Follow the instructions and complete the login steps.

4. Download docfx nuget package from GitHub Packages
Copy link
Contributor

Choose a reason for hiding this comment

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

Should we recommend adding GitHub feed URL to NuGet.config?

Copy link
Contributor Author

@filzrev filzrev Nov 19, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Should we recommend adding GitHub feed URL to NuGet.config?

I don't consider it particularly necessary.
GitHub Packages requires PAT token for using public packages.
So It's simpler downloading nupkg by using gh command and REST APIs.

Examples of using GitHub Packages with NuGet.confg

  1. [Feature Request] Publish docfx prerelease version NuGet packages #9609 (comment)

  2. docfx/.github/workflows/nightly.yml

    Lines 55 to 76 in 5d68cfe

    - name: Create NuGet.config
    shell: pwsh
    run: |
    @'
    <?xml version="1.0" encoding="utf-8"?>
    <configuration>
    <packageSources>
    <clear />
    <add key="github" value="https://nuget.pkg.github.com/dotnet/index.json" />
    </packageSources>
    <packageSourceCredentials>
    <github>
    <add key="Username" value="%USER%" />
    <add key="ClearTextPassword" value="%GITHUB_TOKEN%" />
    </github>
    </packageSourceCredentials>
    </configuration>
    '@ | Out-File NuGet.config -Encoding UTF8
    - name: Install nightly build package
    run: |
    dotnet tool install docfx -g --prerelease

Copy link
Contributor

Choose a reason for hiding this comment

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

Ok, people should find how to authenticate against GH packages if they want to use NuGet.config.


```pwsh
# Gets Access Token
$token = gh auth token

# Gets the version of latest nightly build
$version = gh api /orgs/dotnet/packages/nuget/docfx/versions --jq '.[0].name'

# Gets nupkg download URL.
$downloadUrl = "https://nuget.pkg.github.com/dotnet/download/docfx/${version}/${version}.nupkg"

# Download nupkg to current directory.
Write-Host ('Download nupkg from: {0}' -f $downloadUrl)
Invoke-RestMethod -Method Get -Uri $downloadUrl -OutFile "docfx.${version}.nupkg" -Headers @{
Authorization = "Bearer $token"
}
```

5. Install docfx as .NET Global Package from local source

```pwsh
dotnet tool update docfx -g --prerelease --source ./
```

## Next Steps

- [Write Articles](docs/markdown.md)
Expand Down