DotNetSphinx 0.9.0

dotnet-sphinx

A .NET CLI tool that generates Sphinx-compatible API reference files from a .NET project. It reads the API JSON produced by the Lunet extractor and writes reStructuredText (.rst) or MyST Markdown (.md) pages that use the sphinxcontrib-dotnetdomain dn: directives.

Requirements

• .NET 10 SDK or later
• A Sphinx project with sphinxcontrib-dotnetdomain installed

Installation

Publish the tool locally so that its bundled extractor assets are available at runtime:

dotnet publish src/DotNetSphinx -c Release -o out /p:UseAppHost=false

Then invoke the published binary:

dotnet out/DotNetSphinx.dll generate -p path/to/MyLibrary.csproj -o docs/api

Usage

dotnet DotNetSphinx.dll generate --project <path> --output <dir> [options]

Sphinx configuration

Install the domain extension:

pip install sphinxcontrib-dotnetdomain

Add it to your conf.py:

extensions = [
    "sphinxcontrib.dotnetdomain",
    # ... other extensions
]

Then add the generated index.rst (or index.md) to a toctree in your Sphinx project.

Suppress config

Pass --suppress-config path/to/suppress.json to hide internal types and control cross-reference rendering. Example:

{
  "suppressTypes": [
    "MyAssembly.Internal.HelperClass"
  ],
  "suppressNamespaces": [
    "MyAssembly.Internal.*"
  ],
  "suppressSourceAssemblies": [
    "MyAssembly"
  ],
  "suppressXrefPrefixes": [
    "ThirdParty."
  ],
  "ignoreAttributes": [
    "DebuggerDisplay",
    "EditorBrowsable"
  ]
}

Troubleshooting

"Extractor props not found" — The tool must be run from a published output directory, not directly via dotnet run. Publish first with the command above.

No *.api.json files produced — Run a clean build before generating:

dotnet clean && dotnet publish src/DotNetSphinx -c Release -o out /p:UseAppHost=false
dotnet out/DotNetSphinx.dll generate -p path/to/MyLibrary.csproj -o docs/api

Sphinx warns about unknown dn: roles — Ensure sphinxcontrib-dotnetdomain is installed and listed in conf.py extensions.

Learn more

Read the project announcement and background on the LeXtudio blog: https://docs.lextudio.com/blog/a-brief-history-of-dotnet-documentation-tools-and-the-new-dotnet-sphinx/

Acknowledgements

This project uses Lunet (included as a submodule) for API extraction and model handling.

License

MIT — see LICENSE.

Copyright

Copyright (c) 2026 LeXtudio Inc. All rights reserved.