[Feature]: Generate API documentation for documented symbols in a package

[JonDouglas]

Related Problem

No response

The Elevator Pitch

NuGet.org should provide public API documentation for every NuGet package it ingests similar to other package ecosystems:

That's it. That's the pitch!

Future opportunities could be helping empower developers comment their public API surface further and providing API knowledge / docs to our AI overlords.

For more context, the Learn team at Microsoft currently has an API generation docfx/mdoc-type of solution that can take in a NuGet package and generate a API documentation page similar to https://learn.microsoft.com/en-us/dotnet/api/microsoft.csharp.csharpcodeprovider?view=net-8.0

Additional Context and Details

No response

[Aaronontheweb]

So currently on our documentation, we filter out some namespaces and other parts of our "public" API that really aren't meant for public consumption (i.e. internals that other contributors + plugin authors can access, but not something end-users should be using regularly). How would I express that same idea on NuGet.org?

[Aaronontheweb]

Also, just generally - would I be able to opt my packages out of this feature?

[JonDouglas]

Also, just generally - would I be able to opt my packages out of this feature?

I haven't seen this as a pattern, but I'm sure it is possible. What scenarios would you not want to have public API docs generated for people to look through when browsing your packages?

[Tarmil]

So currently on our documentation, we filter out some namespaces and other parts of our "public" API that really aren't meant for public consumption (i.e. internals that other contributors + plugin authors can access, but not something end-users should be using regularly). How would I express that same idea on NuGet.org?

The xmldoc tag <exclude /> is recognized by tools like Sandcastle and FSharp.Formatting, it would make sense to use it here too.

[SimonCropp]

@Aaronontheweb perhaps u could use ExperimentalAttribute. then any rendered docs could exclude APIs with ExperimentalAttribute. and potentially have a toggle to show them

[Aaronontheweb]

@SimonCropp we have an 'InternalAttribute' tag we use

[SimonCropp]

@Aaronontheweb note that ExperimentalAttribute has compiler level support. so for someone to use it they explicitly need to opt in to that allow Experimental API use. if they dont it will be a compiler error. so in a similar way to how the ObsoleteAttribute works

[SimonCropp]

IMO ExperimentalAttribute should have been named a bit more generically. something like HereBeDragonsAttribute

[baronfel]

It's important to consider API docs as just a first step. There are other important docs concepts like conceptual, guided walkthroughs, etc - and eventually (not necessarily for v1) it would be great to have a good base-level centralized hosting for those as well. For prior art I'd consider looking at the split between the docs on crates.io and docs.rs for Rust. Let's take the bitvec package for example:

• crates.io
• docs.rs

The crates.io page is just the README (but it's very lovingly rendered!), but it links to the generated documentation. The docs.rs page has the deeper docs. Takeaways from my point of view:

• Packages should link to documentation, and have documentation focused on the nuget.org view.
• The linked documentation should be 'pluggable' - nuget.org rendered docs might be a good default or baseline, but package authors should be able to provide a way to disable/skip documentation generation and point to their own docs.
• Package authors are going to have opinions/needs for customizing docs generation - the docs generation system IMO should be open source and extensible (even if it runs on Microsoft- or .NET Foundation-managed hardware) to provide transparency and enable community contributions/enhancements.