Skip to content

README.md

Latest commit

 

History

History
120 lines (86 loc) · 3.72 KB

README.md

File metadata and controls

120 lines (86 loc) · 3.72 KB

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

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]
Option Short Description Default
--project -p Path to the .csproj file (required)
--output -o Output directory for generated files (required)
--config -c Build configuration Release
--framework -f Target framework moniker (e.g. net8.0) (auto)
--rst Emit reStructuredText .rst files (default)
--md Emit MyST Markdown .md files
--suppress-config Path to a suppress config JSON file
--max-slug-length Maximum filename slug length 96

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"
  ]
}
Key Effect
suppressTypes Fully-qualified type names to exclude from output
suppressNamespaces Glob patterns for namespaces to exclude
suppressSourceAssemblies Assemblies for which source links are omitted
suppressXrefPrefixes UID prefixes rendered as code literals instead of :any: cross-references
ignoreAttributes C# attributes stripped from displayed syntax blocks

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.