dotnet / dotnet/docfx

[Bug] Ignoring global namespace prevents metadata to generate api folder

Open
#9,978 5 comments 0 reactions 0 assignees View on GitHub
dotnet
Dominant language
C#
Stars
4.4k
Forks
890
Avg merge
2h 11m
Merged PRs (30d)
10

Description

**Describe the bug**

I'm using Unity and making common libraries. I hope to generate docs using the C# source code, cuz current dotnet version won't well restore Unity csprojs. (`dotnet restore` will output `Nothing to do` or something alike, and docFX will freeze there, but this is not a problem to me).

I use filterConfig.yml and exclude `Global` namespace in it (I have `"globalNamespaceId": "Global"` in docfx.json), but this prevents the metadata to generate the destination dir.

The content of my filterConfig.yml
```
apiRules:
- include:
uidRegex: ^MyNamespace$
type: Namespace
- exclude:
uidRegex: Global
type: Namespace
```
Things work quite well if I don't have this exclude part.

**To Reproduce**
Steps to reproduce the behavior:
1. Create a unity project and set the docfx.json, filterConfig.yml as follows. The dir that contains docfx.json should be parallel to the Assets/ folder of the unity project. However I don't think this is fully necessary. One can just create similar folder structures as a Unity project.
2. Write some code in the global namespace, and some other code in `MyNamespace` namespace.
3. After initializing the docFX folder, run `docFX docfx.json --serve` or things alike.

**Expected behavior**
The destination folder (`api`) should exist but doesn't.

**Context (please complete the following information):**
- OS: MacOS 14.4.1 + intel chips
- Docfx version: 2.76.0
- .NET version: 8.0.301 (output by dotnet --version)

- `docfx.json` config

```json
{
"metadata": [
{
"allowCompilationErrors": true,
"src": [
{
"src": "..",
"files": [
"Assets/MyScriptFolder/**/*.cs"
],
"exclude": [
"Assets/MyScriptFolder/**/Demo/"
]
}
],
"globalNamespaceId": "Global",
"filter": "filterConfig.yml",
"dest": "api"
}
],
"build": {
"globalMetadata": {
"_appTitle": "MyTitle",
"_appFooter": "MyFooter",
"_enableSearch": true
},
"content": [
{
"files": [
"**/*.md",
"**/toc.yml",
"api/**.yml"
],
"exclude": [
"obj/**",
"_site/**"
]
}
],
"dest": "_site",
"globalMetadataFiles": [],
"fileMetadataFiles": [],
"template": null,
"postProcessors": [],
"noLangKeyword": false
}
}
```

- Exceptions

```csharp
// Paste the full exception with stacktrace here, remove sensitive info
```

- Errors and warnings

```csharp
// Paste warnings or errors related to this bug here, remove sensitive info
```

- .NET info

```csharp
❯ dotnet --info
.NET SDK:
Version: 8.0.301
Commit: 1a0e9c0300
Workload version: 8.0.300-manifests.f6879a9a
MSBuild version: 17.10.4+10fbfbf2e

Runtime Environment:
OS Name: Mac OS X
OS Version: 14.4
OS Platform: Darwin
RID: osx-x64
Base Path: /usr/local/share/dotnet/sdk/8.0.301/

.NET workloads installed:
There are no installed workloads to display.

Host:
Version: 8.0.6
Architecture: x64
Commit: 3b8b000a0e

.NET SDKs installed:
8.0.301 [/usr/local/share/dotnet/sdk]

.NET runtimes installed:
Microsoft.AspNetCore.App 8.0.6 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
Microsoft.NETCore.App 8.0.6 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]

Other architectures found:
None

Environment variables:
Not set

global.json file:
Not found

Learn more:
https://aka.ms/dotnet/info

Download .NET:
https://aka.ms/dotnet/download
```

**Additional context**
Add any other context about the problem here.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.