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?