Unable to use DocFx on Unity

[EricBatlle]

Hi, following your README instructions I can display some Scripting API site if I use your own repo.

But if I try to make the same steps on a new project (empty for the exception of 1 .cs script) that is not uploaded on github I get the following errors:

I let the docfx.json exactly like yours and filterConfig.yml looks like:

Apparently seems to have one problem trying to create/find api folder, how can I solve this?

Thanks!

[NormandErwan]

If you want to include all C# scripts, you can go simpler by removing this line on your Documentation/docfx.json:

{
  "metadata": [
    {
      ...
-     "filter": "filterConfig.yml",
      "dest": "api/"
    }
  ],
  ...
}

Have you generated the .csproj files with Unity? DocFX is using them to generate the docs. On Unity, click Asset > Open C# Project to generate them.

[EricBatlle]

Thanks for the JSON advice.

I've generated the .csproj as you said:

But the documentation still not works :S

[NormandErwan]

I think it's related to Powershell. Can you try the same commands on Git bash, if you have installed it?

Meanwhile, I'm going to find a solution to be able to use DocFx with Powershell.

[EricBatlle]

Sorry for the big delay Normand, and thanks for still helping me.

I try the same with GitBash and the output was this:

So the problem stills, basically the website generated on localhost have a non-interactable Script API button :( what's next?

[NormandErwan]

Can you try this command: docfx metadata --force Documentation/docfx.json?

DocFX works in two steps: first it extracts your source code data (the metadata subcomnand), then it generates the documentation website (the build subcommand). The bug here is related to the metadata step. I want to try to force it extract metadata from scratch, not using its internal cache from previous time.

[EricBatlle]

Ofc, here's the result:

[NormandErwan]

That would be too easy! We're gonna find :)

What's the content of metadata in your docfx.json?

[EricBatlle]

Yei! That's the content!

[NormandErwan]

Can you add this line on your docfx.json:

     "metadata": [
         {
             "src": [
                 {
                     "src": "..",
                     "files": [ "**.csproj" ]
                 }
             ],
+            "globalNamespaceId": "Global",
             "dest": "api"
         }
     ],

It seems DocFX requires a namespace on all scripts. A default namespace can be attributed on scripts with metadata.globalNamespaceId: https://github.com/dotnet/docfx/pull/1525.

[EricBatlle]

I try the same adding this new line on the metadata field, but the Script API button still doesn't work :( Could be that the "Global" name could be case-sensitive? Edit: nope, that's not the problem, I've tried ^^'

Edit2: Added img if it helps

[NormandErwan]

I don't get it :( Can you send me a zip of your project? I will try on my machine. Meanwhile, I'm digging into DocFX's issues to find hints on this bug.

[EricBatlle]

Absolutly, here is the project: https://mega.nz/#!TtZ3SaAY

[timower]

I have the same problem on MacOS, I've tried creating assembly definitions but still no luck :( It would be nice if DocFX had more logging to debug the problem.

[NormandErwan]

Sorry, I'm late. @ls29322 I can't download it: a password is required.

@timower I agree, it lacks debug information! It's hard to tell why it fails.

[EricBatlle]

Uops, sorry @NormandErwan , link incomplete, here's the correct one: https://mega.nz/#!TtZ3SaAY!5XGr0bTMer5cen-ktS8y2bKpZB49pfuFPADfSVBx8tc

[NormandErwan]

I tried on my machine: after regenerating the C# projects with Unity (Asset > Open C# Project), DocFX generates all metadata.

Your docfx.json is correct and working. It seems on the DocFX issues there were frequent problems with the version of Visual Studio, I understand DocFX is looking for specific version of VS. I'm still digging to find a solution!

DocFX uses Visual Studio 2019 on my machine. I see its VS 2017 on your previous comments. You could download VS 2019 and try DocFX with it?

[NormandErwan]

@EricBatlle Have you tried with VS 2019? :)

[EricBatlle]

No sorry @NormandErwan , I've little (none) space on my disk and I can't download VS2019 ^^' But I don't forget this issue, I'll give you feedback when I try it :D

[NormandErwan]

I'm closing the issue. Feel free to comment if you try again, I'll re-open it!

[gnuumpat]

Hello and sorry for coming back to such an old issue. It appears that I am unable to generate the documentation from my Unity project following along your README file. For some reason, in the metadata phase when docfx tries to compile the source files, it cannot find the Unity namespaces. I recon that I made a mistake somewhere, but were unable to identify it until now.

It doesn't matter if I do it with GitBash, PowerShell or the Command Prompt and I also tried to regenerate my Visual Studio files by deleting it all and then press Assets > Open C# Project in Unity.

Other than that, I use Unity Editor 2022.3.1f1.

Did anyone encounter a similar problem?

[MickDmnts]

@gnuumpat Here for the same reason, trying some things around, I'll notify this post in case I find a workaround.

[David624634]

I had the same issue as @gnuumpat, and what worked for me was using DoxFx Version 2.61.0 instead of the newest version.

[mingyu243]

WOW!!! @David624634 thank you... my docfx version is 2.73.2

error CS0246: The type or namespace name 'UnityEditor' could not be found (are you missing a using directive or an assembly reference?)
error CS0246: The type or namespace name 'UnityEngine' could not be found (are you missing a using directive or an assembly reference?)
error CS0246: The type or namespace name 'MonoBehaviour' could not be found (are you missing a using directive or an assembly reference?)

dotnet tool uninstall -g docfx dotnet tool install -g docfx --version 2.61.0

Now is working... thank you!!!

[kurone-kito]

Certainly, DocFX 2.61.0 works well for me.

As for 2.62.0 or later not working correctly, I thought that was due to dotnet/docfx#8399, but I don't know how to work around this breaking change in newer versions.

[fsedarkalex]

And even worse, docFX 2.61 seems to not work with VS 2019, or did anyone manage to get it running? Doesn't find MSBuild here

[DSOE1024]

您好，很抱歉回到这样一个老问题。看来我无法按照您的 README 文件从我的 Unity 项目生成文档。由于某种原因，在 docfx 尝试编译源文件的阶段，它找不到 Unity 命名空间。我承认我在某个地方犯了一个错误，但直到现在都无法识别它。metadata

不管我是使用 GitBash、PowerShell 还是命令提示符来执行此操作，我还尝试通过删除所有文件来重新生成我的 Visual Studio 文件，然后按 Assets >在 Unity 中打开 C# 项目。

除此之外，我使用 Unity 编辑器 2022.3.1f1。

有没有人遇到过类似的问题？

Yes, I'm having the same issue