Как обслуживать документацию, используя godoc вместе с модулями go?

Простой godoc -goroot=. обслуживает файлы проекта, но он не генерирует документацию для пакетов. Я проверил это из каталога исходных текстов проектов, где также хранятся файлы модулей go.mod и go.sum.

Как создать документацию для всех пакетов внутри модуля Go - за пределами $GOPATH?

В примечаниях к выпуску Go 1.12 написано, что инструмент godoc не будет включен в будущие выпуски Go и будет доступен только через go get после Go 1.12. Нужно использовать команду Go go doc. Однако go doc не генерирует "приятные для чтения" страницы HTML. Есть ли альтернатива для генерации документации из исходного кода Go, которая выводит HTML или Markdown?

Ответы

Ответ 1

Проблема не столько в модулях, сколько в GOPATH. Есть тема GitHub, в которой это обсуждается более подробно: https://github.com/golang/go/issues/26827

Этот поток разработал обходной путь, который использует докер-контейнер для запуска сервера Godoc с GOPATH, установленным в основу вашего дерева разработки. Этот сервер Godoc будет обслуживать документы для всех пакетов в вашем дереве разработки, независимо от того, есть ли у них go.mod или нет.

Вот вариант обходного пути, который я только что опубликовал в этой теме сегодня утром - измените $ devbase (или передайте его как $ 1), чтобы он указывал на основу вашего дерева:

#!/bin/bash 

set -x  # optional

devbase=$HOME/gohack
port=6060

docker run \
    --rm \
    -e "GOPATH=/tmp/go" \
    -p 127.0.0.1:$port:$port \
    -v $devbase:/tmp/go/src/ \
    --name godoc \
    golang \
    bash -c "go get golang.org/x/tools/cmd/godoc && echo http://localhost:$port/pkg/ && /tmp/go/bin/godoc -http=:$port"

Вы заметите, что я также использую инструмент gohack - он управляет строками 'replace' в go.mod для вас, поэтому при импорте будет найдена ваша локальная версия модуля, даже если он еще не отправлено на сервер. В остальном ничего особенного в $ devbase нет - например, указание на $ HOME/src должно работать так же хорошо.