search

gnolang / gno

Gno: An interpreted, stack-based Go virtual machine to build succinct and composable apps + Gno.land: a blockchain for timeless code and fair open-source
https://gno.land/
Other
849 stars 345 forks source link

Publish godoc of this repo #1059

Closed moul closed 6 months ago

moul commented 10 months ago

Problem: Currently, we're facing an issue with pkg.go.dev not recognizing our custom LICENSE, which is preventing the display of our project's generated documentation.

Solution: To work around this, we've decided to use the official godoc -http tool. We've laid the initial groundwork for this approach in this pull request: #884.

Next Steps:

  1. Verify Generated Documentation: Since we're relying on a locally exposed HTTP server, there's a chance of broken links or inaccurate content in the generated documentation. Ensuring that the documentation is correct is essential.

  2. Complete Configuration: We're in the process of finalizing the configuration to enable the display of the generated documentation, potentially through GitHub Pages.

  3. Setting Up a Custom Domain: To make the documentation more accessible, we're considering setting up a custom domain name, which would make it easier to locate.

Related with #1046 (may want to use the same docs.gno.land URL?).

waymobetta commented 10 months ago

Perhaps we could host this on a different subdomain; ie, pkg.gno.land in keeping with the Go documentation server theme (unless we plan on altering this theme) and then have higher-level documentation live on docs.gno.land. If this introduces confusion, we can easily just consolidate into docs.gno.land down the road.

waymobetta commented 10 months ago

We can also utilize an alternative to godoc, a tool called golds if we wished to customize formatting a bit further, otherwise we can stick to godoc if we wish the theme to be more in-keeping with Go.

golds example

Along with different coloration and formatting, golds also provides analytics.

golds example: statistics

Screenshot 2023-08-21 at 1 51 00 PM
thehowl commented 6 months ago

This has been added since https://github.com/gnolang/gno/pull/1251

I think it makes sense for the documentation of the gno repository to live on github.io. Maybe we should consider moving it if we want to move to being GitHub-agnostic in our import paths using vanity imports. (maybe something like src.gno.land for hosting the gno repo, or src.gno.land/gno); in which case that could take the godoc documentation.

In any case, the tool's been developed and works decently (IMO). We can iterate on that.