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

[Bug] DocFx generates incorrect links in "View Source" when building from a tag in Azure DevOps git repo #10161

Open
Maarty opened this issue Aug 20, 2024 · 3 comments
Labels
bug A bug to fix static-site Produce static HTML output ready for publishing to hosts like GitHub pages

Comments

@Maarty
Copy link

Maarty commented Aug 20, 2024

Our builds are usually from a git tag in Azure DevOps, and in this case, the "View Source" button in DocFx is not working.

The link would work if we built from a branch, but not from a tag.

Example of generated link:
https://dev.azure.com/organizationName/projectname/_git/RepoName?path=Src/path/subpath/file.cs&version=GB7.104.0&line=8

7.104.0 is the name of our git tag.

Correct link would end with GT7.104.0 not GB7.104.0 as GB works only for branches, not tags.

To Reproduce
Steps to reproduce the behavior:

  1. Run CLI dotnet docfx on a git tag version of Azure DevOps repo.

Expected behavior
The link should end with GT{tag name} instead of GB{tag name} for builds from a git tag.

Context:

  • OS: Windows/Linux
  • Docfx version: latest
@Maarty Maarty added the bug A bug to fix label Aug 20, 2024
@VaclavElias
Copy link
Contributor

VaclavElias commented Sep 1, 2024

This might be similar to my issue. This checkouts from 2 repositories https://github.com/stride3d/stride-docs/blob/staging/.github/workflows/stride-docs-staging-azure.yml

  • Stride Docs - From the repository and branch staging where the GitHub Action is triggered from
  • Stride Engine - Used for the API generation, checkout from another repository, with master branch

The documentation manual, tutorials.. honor the settings from the docfx.json, so when I click Edit this page, it takes you to the correct repo and branch.

"_gitContribute": {
        "repo": "https://github.com/stride3d/stride-docs",
        "branch": "master"
      }

But when I want to see the source code for the API, for example here https://stride-doc-staging.azurewebsites.net/latest/en/api/Stride.CompilationMode.html

The View Source links takes you to

https://github.com/stride3d/stride/blob/staging/sources/engine/Stride/CompilationMode.cs/#L8 which doesn't exist.

The branch shouldn't be staging but master.

The GitHub Action (link above) has this:

    # Checkout the Stride repository from the default branch
    - name: Checkout Stride (note the LFS)
      uses: actions/checkout@v4
      with:
        repository: stride3d/stride
        token: ${{ secrets.GITHUB_TOKEN }}
        path: stride
        lfs: true
        ref: master

It seems like that the current branch staging is somehow leaking where it shouldn't 🤣.

Tested on version 2.77.0.

@filzrev
Copy link
Contributor

filzrev commented Sep 3, 2024

The link should end with GT{tag name} instead of GB{tag name} for builds from a git tag.

Source URLs are generated by following files.

But currently it seems GT{tag name} link is not supported.
If there is a way to get current checkouted branch is tag or not. (e.g. Build.SourceBranch environment variable)
It can add support for GT type links.


@VaclavElias

But when I want to see the source code for the API, for example here
https://stride-doc-staging.azurewebsites.net/latest/en/api/Stride.CompilationMode.html

I though staging branch name seems be taken from GITHUB_REF_NAME environment variable. `https://github.com/dotnet/docfx/blob/main/src/Docfx.Common/Git/GitUtility.cs#L22

It might be resolved by clearing this environment variable.
(I thought environment lookup logics are added for perf optimization.
It might be able to remove these logics. Because currently external git command call is not exists)

The documentation manual, tutorials.. honor the settings from the docfx.json, so when I click Edit this page, it takes you to the correct repo and branch.

It seems currently _gitContribute settings is not applied to view source link.
https://github.com/dotnet/docfx/blob/main/templates/common/common.js#L33-L39

@VaclavElias
Copy link
Contributor

Thanks @filzrev, I will give it a go regarding GITHUB_REF_NAME and report back.

@yufeih yufeih added the static-site Produce static HTML output ready for publishing to hosts like GitHub pages label Sep 23, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug A bug to fix static-site Produce static HTML output ready for publishing to hosts like GitHub pages
Projects
None yet
Development

No branches or pull requests

4 participants