Maps for Unity versions newer than 2020.2 are missing

[OscarAbraham]

Hello,

I get 404 errors when trying to download maps for Unity versions newer than 2020.2. For example:
This URL doesn't work: https://normanderwan.github.io/UnityXrefMaps/2021.3/xrefmap.yml
This URL does work: https://normanderwan.github.io/UnityXrefMaps/2020.2/xrefmap.yml

Thanks!

[NormandErwan]

Yes, the GitHub action that builds the maps is down. I'll try to fix as soon as possible.

[ugnmura]

Any updates on this one?

[NormandErwan]

I fixed the program, but it fails on the GitHub action for some reason I don't understand... I'll give it another try!

[NormandErwan]

It's still a work in progress. The GitHub action is running, but only recent versions (2022.x and 2023.x) are generated and online. I'm looking for a workaround.

[OscarAbraham]

@NormandErwan Here's what I've found while trying to fix this issue some time ago, in case it helps: I couldn't make it work well, even locally. Some versions of DocFX and .Net worked with older versions, and some worked with newer ones. I probably should have shared this here then, sorry; I though I'd try again later and I forgot.

I don't feel I know enough about .Net to suggest how to fix this properly. I've found that a map generated from the 2022.2 branch works well with 2021.3 projects; most API links from 2021.3 are present in 2022.2. So, if a proper fix is proving to be too hard, maybe a good-enough workaround could be to retrofit newer maps into links for older Unity docs? Even if you wanted to abandon maps for older versions completely, I think the newer maps could work well enough for most projects.

Finally, I want to take this opportunity to say that this project is awesome. I've found it very useful. It makes documentation pages so much better. Thank you.

[NormandErwan]

Thank you very much for these very kind words!

Also for this input, it will definitively help! You're right, I noticed also that depending on the .NET and DocFX versions, different maps can be generated.

It's a good suggestion to generate only the new ones and keep the previous ones, instead of regenerating everything. I will probably do that.

[NormandErwan]

I have manually generated all the missing xrefmaps and uploaded them to the gh-pages branch. They are ready for use at https://normanderwan.github.io/UnityXrefMaps/20XX.Y/xrefmap.yml.

The GitHub action must be missing some configurations because it works fine on my machine.

Still, the GitHub action will generate and update the 2022 and 2023 versions. I think that's ok, the older versions won't move that far. If needed, I will manually generate and upload the older versions.

[NormandErwan]

It's interesting. It seems that with DocFX 2.61.0 it's possible to generate Unity xref maps 2021 and lower, but not 2022 and 2023. However, higher versions of DocFX can only generate 2022 and 2023, not 2021 and lower.

[StephenHodgson]

I was able to figure this out actually. It seems for versions between 2019.1 and 2021.3 you had to pass Debug configuration.

https://github.com/RageAgainstThePixel/UnityDocfxXrefMaps/blob/6dd469a982b58a9d08d75c0cc4319aa39c67ed10/generate-xref-maps.ps1#L238-L243

            if ($version -ge "2019.1" -and $version -le "2021.3") {
                docfx metadata $DocfxPath --output $versionFolder --logLevel error --property Configuration=Debug
            }
            else {
                docfx metadata $DocfxPath --output $versionFolder --logLevel error
            }