search

NuGet / NuGetGallery

NuGet Gallery is a package repository that powers https://www.nuget.org. Use this repo for reporting NuGet.org issues.
https://www.nuget.org/
Apache License 2.0
1.52k stars 643 forks source link

[Feature]: DNDocs #10055

Open NeuroXiq opened 3 weeks ago

NeuroXiq commented 3 weeks ago

Related Problem

https://github.com/NuGet/NuGetGallery/issues/6946 https://github.com/NuGet/NuGetGallery/issues/9776

The Elevator Pitch

Short description

Looking on github.com repositories and nuget.org packages I noticed that lots of them does not have documentation online. If I want to see classes, methods etc. I need to open source code and look in the C# code about implemented feature. This is cumbersome.

I created DNDocs to host API Explorer exactly for this problem: https://dndocs.com/i/nuget/AutoMapper/13.0.1 https://dndocs.com/i/nuget/Microsoft.EntityFrameworkCore/8.0.3

Long description

DNDocs is a simple API Explorer (documentation hosting platform). DNDocs allows to generate and host API Docs online using Docfx. After generating a project, server do not delete it - generated docs are stored on the server disk (cached) and available immediately after generation. So generating occurs only once and can took 1-5 minutes and then Docs are accessible immediately.

To Explore nuget package replace values in URL and open the page: https://dndocs.com/i/nuget/{NugetPackageName}/{NugetPackageVersion} Wait 1-5 minutes (if server generate is for the first time) and just click green button on the right.

Additional informations

For example, people want to have API Explorer and I think DocFX can fit well here:

https://github.com/NuGet/NuGetGallery/issues/6946 https://github.com/NuGet/NuGetGallery/issues/9776

And also some people on github hosts docs on DNDocs: https://github.com/madelson/DistributedLock https://github.com/betalgo/openai https://github.com/adamhathcock/sharpcompress

Summary

So thats all what I want to say in this request. I would like to hear Your opinion about this feature and DNDocs project. I'm open to any and all ideas.

Best Regards Marek Węglarz / NeuroXiq https://github.com/NeuroXiq/DNDocs

Additional Context and Details

Screenshots:

image

image

image

image

image

image

image

No response

erdembayar commented 3 weeks ago

If you have a screenshot, please add it here. We need to triage first based on the information you provided to us.

erdembayar commented 2 weeks ago

@JonDouglas Could you please take a look?

MangelMaxime commented 1 week ago

Coincidentally, we (F# community) are working on a similar project for F# APIs.

I wanted to point it how, because it looks like DNDocs is considering that all package published to NuGet are C# packages.

CleanShot 2024-07-14 at 20 03 40

versus

type [<AllowNullLiteral>] ArrayConstructor =
    [<Emit "new $0($1...)">]
    abstract Create: size: int -> 'T[]

I am mentioning this because, I think it is important to note that perhaps multiple services could need to be supported.

joelverhagen commented 1 week ago

This tool looks really cool. The feature has been on the back of my mind for years. As you mentioned, there are existing feature requests from 2019.

The need was filled for a while by FuGetGallery. However, FuGetGallery has had availability issues and we disabled the link (https://github.com/NuGet/NuGetGallery/issues/9783).

I have some questions, @NeuroXiq.

  1. Where is the source code for the project? I found https://github.com/NeuroXiq/DNDocs but this seems to just be an issue tracker. Is the project open source? In particular, I'd like to look at the way you fetch package content from our APIs. I also see some typos. The community may be able to help improve DNDocs in these cases if it is open source.
  2. How are deleted packages handled? When a package is removed from NuGet.org, will it be cached indefinitely by DNDocs? From time to time there are malicious and DMCA takedowns on NuGet.org. IMO it would make sense to periodically remove deleted package content from DNDocs. This could be detected by a catalog reader (guide, API) looking for PackageDelete events or via a cache timeout.
  3. What are your scalability targets? Said another way, do you expect it to be able to handle a lot of load? If we enabled this from NuGet.org, I expect the background job queue to grow somewhat as folks browse packages seeking API docs.
  4. What package types are handled? I tried a normal dependency package and it worked well, but a CLI tool redirected me to a login page for some reason. When I queued by package name I got an error. There are other package types DotnetTool, Template, DotnetPlatform, MSBuildSdk, AzureSiteExtension, DotnetCliTool, etc.
  5. Does the link to DNDocs make sense when the package already has API documentation linked elsewhere? I feel like it could be confusing to the user that they may not know which is the "official" API documentation site.
  6. Akin to @MangelMaxime's question, how are packages with different languages handled? I see F# doesn't work as expected. I wonder how native dependencies or VB.NET IL are handled. What about packages containing JS or .exe (legacy scenarios)?
  7. Can a package author request a takedown? If a package author does not want their content hosted on DNDocs, what kind of controls do they have?
  8. Suppose a type is public but the package author does not want to document it (perhaps it is a legacy API) or have it appear in their DNDocs site. How would they control the final shape of the API docs?
  9. What security considerations or mitigation do you have? I wonder what tools are run on the package and if the possibility of XSS exists.
  10. When is a GitHub login required? I saw it when I tried loading a .NET tool package and I am not sure when login is required. Ideally, the link from NuGet.org would not immediately land on a sign in page. It would break the flow of anonymous NuGet.org navigation.
  11. Could you preempt the "job waiting" delay and/or the "Open API explorer" extra link click by building API docs for all packages on NuGet.org? I am guessing this is an expensive compute-wise for you therefore the work is done on demand. But you could discover packages as they are published via the catalog API (as mentioned above for deletes) and pre-cache the API docs in all applicable cases.

Overall, this is an amazing project and I applaud your contribution to the .NET ecosystem. This may fill a need that FuGetGallery once filled.