feat: major improvements

[bdovaz]

I've done a lot of things, you can really see it in the README.md file in the Advanced usage section.

If you're still interested in maintaining this project (I hope you are), I'll add you as the owner of the NuGet package.

Highlights:

• Stop hardcoding as much as possible and make it parameterizable so that it is compatible even with Unity packages and not just with the editor.
• Project converted to cli distributed in NuGet as a cross platform dotnet tool.
• There is a main command that generates the xrefmap file.
• There is a test command that, when passed an xrefmap file, allows you to test the links in the href field.
• Test the cli commands.
• Patch a few more cases with string replace so that it generates the documentation correctly.

I haven't fixed the github pages workflow in this PR (it's been failing since November 2024) with the new changes because, at the very least, this PR dotnet/docfx#10827 that I created due to a problem that occurs when trying to generate the UnityEngine xrefmap needs to be merged.

[bdovaz]

@NormandErwan ping!

[NormandErwan]

Hello, and thank you very much for this PR. I quickly looked over the changes, and they seem to be a very good improvement!

I have very little time these days, but I will do my best to merge them.

Thank you for your proposal regarding the NuGet package. However, it is your work, so I would prefer you to remain the owner.

[bdovaz]

Thank you for your proposal regarding the NuGet package. However, it is your work, so I would prefer you to remain the owner.

Maybe I didn't explain myself well. What I mean is that in NuGet, packages can have N owners.

And since the GitHub Actions workflow publishes the package, you should configure the related secrets in your repository. Because right now it's published from my fork.

[NormandErwan]

Hi, I'm very sorry for the delay. I'm finally testing, it's very nice, thank you for your work!

I've also seen that dotnet/docfx#10827 has been merged, would you like to fix the github pages workflow as well?

[bdovaz]

would you like to fix the github pages workflow as well?

@NormandErwan done: https://github.com/bdovaz/UnityXrefMaps/tree/gh-pages

6000.0 LTS example: https://bdovaz.github.io/UnityXrefMaps/6000.0/xrefmap.yml

It took me quite a while because I used Unity's releases API:

https://services.docs.unity.com/release/v1/

And it has the problem that the tags in the UnityCsReference repository are always behind, since it seems that they only commit from time to time and it's never synchronized... So I had to create a logic that tries to resolve the tag closest to the one resolved by the releases API.

On the other hand, versions 2019.2 and 2019.1 fail. I don't know if the project structure was different in these versions

https://github.com/bdovaz/UnityXrefMaps/actions/runs/19927828874

I have also made sure that the deployment does not fail because a specific version fails, but rather that it tries to deploy whatever it can.

I have also created tests for xref href fixes and corrected many cases of packages where Unity with docfx generates completely different URLs.

[NormandErwan]

Thanks for all the work!

However, I fail to understand the changes made to the github pages workflow. Why use PowerShell scripts (38757a6)? It seems duplicated code to me.

Instead, we could simply run the dotnet program from this repository instead. I was able to generate the 6000.0 xrefmap on the main branch: 05f3a3c

The objective I had with this project was to generate Unity's xrefmaps using a simple dotnet program.

[bdovaz]

@NormandErwan The main change I made was that the application no longer had any hardcore behavior, which is why you could previously run it without any parameters.

With this PR, what I do is allow anyone to obtain the xref file from the Unity repository “UnityCsReference” or from any package repository that is on GitHub or mirrored thanks to needle-mirror.

This obviously means that you have to pass the repository URL and the git tag to clone as a CLI parameter, and that's where the PowerShell scripts come in. As I said, they use Unity's release API and then get the closest version of each X.Y branch (== git tag) that is in the UnityCsReference repository because they don't commit to that repository very often.

This way, that workflow will “always” work (unless something breaks in the API or repository) automatically, as I have already shown you in a previous comment.

[NormandErwan]

Thanks for your detailed explanation. My initial idea was to list the git tags directly from the UnityCsReference repository and generate a xrefmap for each tag, i.e. Unity X.Y version.

This is how the program currently behaves. If a tag is specified as an argument, only the xrefmap for that version is generated. Otherwise, xrefmaps for all versions are generated.
I also think this would be a useful feature to keep for generating xrefmaps for all versions of a package other than UnityCsReference.
It also seems simpler to keep that feature directly in the dotnet program, rather than adding PowerShell scripting, which I'm not familiar with.

What do you think about keeping this approach?

[bdovaz]

@NormandErwan I have made the --repositoryTags parameter optional, and if it is not passed, it follows the logic you had and mentioned in your message.

Regarding the GitHub Actions workflow, I think what I have done is better because, by using the releases API, it allows filtering and only generating it for currently supported builds.

This means that:

• Execution is more optimal because it will not generate APIs that are not LTS, SUPPORTED, or TECH. It makes no sense to generate 2017.x or 2018.x, for example, since, as I said, even 2019.1 / 2019.2 is not capable of generating anything.
• By relying on that API, it will “automatically” change over time, i.e., when a version is no longer supported, that API will automatically stop returning that version and will stop processing it. Git tags are static, but the API is not.

And with regard to knowledge of PowerShell, I offer to be a co-maintainer of this repository because by the time you merge this PR, I will have acquired a great deal of knowledge about this project and can contribute a lot in the future. And it is always better for an open source project not to depend solely on one person for the health of the project.

If you look at my experience in my profile, you will see that I maintain several projects together with other people or that the entire project was transferred to me:

• https://github.com/bdovaz/UnityNuGet -> the project was transferred to me
• https://github.com/oxsecurity/megalinter/ -> I am a co-maintainer
• https://github.com/Dinomite-Studios/unity-azure-pipelines-tasks -> I am a co-maintainer

[NormandErwan]

I completely agree with you. Thank you very much for your detailed answers and all your work. I indeed think you now know this project better than me. Perhaps it would be best to transfer it to you?

[bdovaz]

I completely agree with you. Thank you very much for your detailed answers and all your work. I indeed think you now know this project better than me. Perhaps it would be best to transfer it to you?

If you think you don't have time to dedicate to it, you can transfer it to me.

If you think you will have time, you can give me permissions and we can both be maintainers of the project

[NormandErwan]

I have just added you as collaborator to the repo. I think we also need to configure the Nuget repo?

[bdovaz]

@NormandErwan, what is your NuGet username? I just created an organization, but I need to add you.

[NormandErwan]

Here's my NuGet username: NormandErwan. Thank you!

[bdovaz]

I have created an organization in NuGet called UnityXrefMaps and invited you as a contributor.

I have set the organization UnityXrefMaps as the owner of the package UnityXrefMaps.

I have created a Trusted Publishing called UnityXrefMaps and associated the organization and the repository with it.

https://learn.microsoft.com/en-us/nuget/nuget-org/trusted-publishing

You need to create a secret called NUGET_USER and put your NuGet username. See: https://devblogs.microsoft.com/dotnet/enhanced-security-is-here-with-the-new-trust-publishing-on-nuget-org/#minimal-github-actions-example-⚙️