Documentation on pkg.go.dev for v4

[tacerus]

Hi,

https://pkg.go.dev/github.com/netbox-community/go-netbox/v4 does not have any function and type references, the "Documentation" section states "Documentation is too large to display.", and the "Directories" section is missing.
For v3, at https://pkg.go.dev/github.com/netbox-community/go-netbox/v3, one finds a "Directories" section under which can browse "netbox" and find relevant information.

One can search for symbols directly, for example via https://pkg.go.dev/search?limit=25&m=symbol&q=VirtualizationAPI.VirtualizationVirtualMachinesCreate, but clicking the results just yields the module homepage.

Of course, one can still browse the source files, but it's not as convenient for quick referencing - am I missing something to reach the "rendered" documentation for v4?

[nutgood]

Hey,

So this is a 100% generated library and the go generator doesn't generate much inline docs.

It does generate a docs/ folder with some amount of docs but it's enormous and vaguely helpful at best, I usually remove it before merge since PRs are already enormous.

You can see an historical example here.

Do you think it would be helpful to leave those in ?

[nutgood]

Feel free to experiment with generator settings and open a PR if you have something that make sense ! Do note that I do not accept PRs that have complete code change since diffs are wildly large and it's impossible for me to validate that they don't have malware code but I'll accept PRs that have change to tests, configuration, scripts and others and I will re-generate the library myself.

[tacerus]

Will check, and sure, that makes sense.

[tacerus]

Running the generator on the current master and executing pkgsite (offline pkg.go.dev) always returns

2025/02/24 20:27:25 Warning: executeToHTMLWithLimit failed: limit=40000000, remain=-131

upon loading the page, which correlates to "Documentation is too large to display" being rendered

It seems it's not related to docs/, since that also returns if running without a docs/ directory, but I cannot find what other files it would correspond to (I guess it's the expanded size of the templates).

Splitting the files into smaller modules would probably be the solution, but that's not supported by the generator (besides being a breaking change).

[nutgood]

Indeed. There's oapi-codegen which is a generator which supports that but it would be one heck of a breaking change.

For now I'll stick with guiding people in the right direction whenever they have usage question, it's less of a hassle.

[tacerus]

Just for reference, not something I would propose, my non-idiomatic solution for browsing through pkgsite without altering the module layout itself: tacerus@ca7c899. :-)