dotnet / docfx

Static site generator for .NET API documentation.
https://dotnet.github.io/docfx/
MIT License
4.01k stars 853 forks source link

Class inheritance generated properly only when nuget packages can be resolved and code is compiled as binary as well #5595

Open ibruynin opened 4 years ago

ibruynin commented 4 years ago

Operation System: Windows

DocFX Version Used: 2.50.0.0

Template used: default

Steps to Reproduce:

  1. Create AbstractApi in namespace1 (dotnetcore3.1 project A)
  2. Create ConfigurationApi in namespace2 (dotnetcore3.1 project B)
  3. docfx init -q
  4. Copy source in src/ 5a. run docfx docfx,json --serve without compiled code in the ./src folder 5b. run docfx docfx,json --serve with compiled code in the ./src folder

Expected Behavior:

The inheritance tree on ConfigurationApi should render properly

Actual Behavior:

When running docfx without compiled code.

The inheritance tree is not rendered properly System.Object > ConfigurationApi

image

When running docfx with compiled code.

The inheritance tree is rendered properly System.Object > AbstractApi > ConfigurationApi image

ibruynin commented 4 years ago

Please find the complete repro case here:

Inheritance not properly documented

create namespace 1

dotnet new classlib -n docfxns1
Write-Output "using System;`n`n`nnamespace docfxns1`n{`n    public class AbstractApi`n    {`n        public void ExistingMethod()`n        {`n`n        }`n    }`n}`n" | Set-Content -Path "docfxns1\\Class1.cs"

create namespace 2

dotnet new classlib -n docfxns2
Write-Output "using docfxns1;`nusing System;`n`nnamespace docfxns2`n{`n    public class ConfigurationApi : AbstractApi`n    {`n        public void NewMethod() { }`n    }`n}" | Set-Content -Path "docfxns2\\Class1.cs"

run docfx

docfx init -q
robocopy docfxns1 docfx_project\src\docfxns1 /mir
robocopy docfxns2 docfx_project\src\docfxns2 /mir
cd docfx_project
docfx docfx.json --serve

the inheritance tree shows Object > ConfigurationApi

Inheritance documented properly

create local nuget repo

mkdir c:\temp\localnuget

build namespace 1

cd docfxns1
dotnet build
dotnet pack -p:PackageVersion=1.1.0
dotnet nuget push bin\Debug\docfxns1.1.1.0.nupkg -s c:\temp\localnuget
cd ..

build namespace 2

cd docfxns2
(Get-Content -Path "docfxns2.csproj").Replace("</PropertyGroup>", "</PropertyGroup><ItemGroup><PackageReference Include=""docfxns1"" Version=""1.1.0"" /></ItemGroup>") | Set-Content -Path "docfxns2.csproj"
dotnet build
cd ..

create docfx API documentation

docfx init -q
robocopy docfxns1 docfx_project\src\docfxns1 /mir
robocopy docfxns2 docfx_project\src\docfxns2 /mir
cd docfx_project
docfx docfx.json --serve

check the documentation

the inheritance tree shows Object > AbstractApi > ConfigurationApi (as expected)

KalleOlaviNiemitalo commented 4 years ago

Does it work if you add a ProjectReference?