Skip to content

Provide docs for defradb package #218

Description

@ribiza

Defra's package docs are not published on pkg.go.dev due to the BSL license. They are also not buildable with godoc due to godoc's incompatibility with submodules and redirect directives, which we use for ex in the Lens package. Godoc is deprecated, anyway.

Collecting possible alternatives here.

pkgsite

https://pkg.go.dev/golang.org/x/pkgsite/cmd/pkgsite

The main limitation is that it doesn't export static files, but only hosts a webserver with docs. The setup with Cloudflare Pages (and anyway a webserver already running for main docs) is not trivial.

People have got to downloading with wget the website and host it themselves
golang/go#2381 (comment)
but some obstacles I've quickly encountered:

  • css exports are sloppy: they get saved in the format licenses.min.css?version=.css, and need to be renamed lest all imports fail
  • crosslinks lead to eg. /defradb/node, but the existing file is /defradb/node.html, so rewrite rules would be needed
  • links to other packages (eg. `Context) don't work

doc2go

https://abhinav.github.io/doc2go/docs/start/

Identified drawbacks:

  • search is not the best: it looks cheap and is not scoped to the package one is looking at
Image

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions