Вопрос или проблема
Работая с python/sphinx, я привык иметь папку “docs” (в sphinx она была бы написана в формате rst) с информацией об использовании/учебниках/справке и т. д., и в этих документах я могу напрямую ссылаться на документацию коду. Папка docs с файлами rst преобразуется в html при сборке.
Таким образом, в документации “how-to” я могу обратиться напрямую к docstring для функции, и этот фрагмент документации кода будет отображаться в моем how-to документе.
Также мне нравятся все дополнительные функции и плагины Rst для других языков и других вещей.
Есть ли что-то подобное в экосистеме godoc? Могу ли я использовать sphinx с godoc? Кажется, что официальной поддержки нет, и все, что я нашел, это эта доблестная, но мертвая попытка: https://github.com/chrisdoherty4/sphinxcontrib-golangdomain. Также, похоже, что возможности godoc очень ограничены в том, какие выходные форматы он поддерживает, поэтому я не могу легко преобразовать его в промежуточный формат и подключить к sphinx.
Я не знаю ни одного инструмента, который позволял бы интегрировать godoc в sphinx, однако вы можете сделать следующее (поскольку ваша цель – HTML-рендеринг):
- генерируйте ваш “how-to” так, как вы привыкли
- ссылайтесь на созданную godoc справочную документацию (пример: https://pkg.go.dev/github.com/fluhus/godoc-tricks#NewExamples)
Если вы хотите самостоятельно размещать сгенерированный godoc, вы можете взглянуть на следующие решения:
- https://code.rocket9labs.com/tslocum/godoc-static
- https://code.pfad.fr/vanitydoc/ (отказ от ответственности: я создал это – не стесняйтесь связаться, если вы хотите поработать над экспортом в .rst 🙂
.
Ответ или решение
В настоящее время интеграция функций Sphinx для работы с документацией на языке Python с системой генерации документации Godoc для Go представляет собой определенные вызовы. В Sphinx, как вы знаете, возможность интеграции документации кода с пользовательской абсолютно реалистична с помощью ссылок на docstring, что обеспечивает гибкость в создании целостных руководств и справочников.
Функционал Godoc, в отличие от Sphinx, более ограничен, особенно в плане расширений и поддержки различных языков разметки. Godoc предназначен для автоматической генерации HTML-документации из аннотаций и комментариев кода Go, но не предоставляет средств прямой интеграции с файлами Sphinx на формате .rst (reStructuredText).
На данный момент не существует официального модуля или расширения, которое бы интегрировало Godoc с Sphinx. Обсуждения и инициативы, такие как проект на GitHub по адресу https://github.com/chrisdoherty4/sphinxcontrib-golangdomain, к сожалению, не получили должного развития и были заброшены.
Однако, если вашей целью является именно рендеринг HTML, вы можете рассмотреть альтернативный подход:
1. Генерация основной документации в формате, к которому вы привыкли с помощью Sphinx, используя все доступные расширения и возможности.
2. Создание ссылок на сгенерированную Godoc документацию, как это делают, например, в Go Reference (https://pkg.go.dev). Это позволит поддерживать актуальность информационных ссылок на документацию кода.
3. Расположение всей документации на одном сервере для консолидации и упрощения доступа. Чтобы реализовать это, можно заняться использованием инструментов для статической генерации Godoc-документации, таких как godoc-static (https://code.rocket9labs.com/tslocum/godoc-static) или Vanitydoc (https://code.pfad.fr/vanitydoc/).
Пока что возможность экспорта в формат .rst для дальнейшего использования с Sphinx отсутствует, но перспективы для такой разработки остаются открытыми. Возможно, создание индивидуального инструмента или скрипта по преобразованию форматов окажется продуктивным решением, если ваша проектная необходимость это оправдывает.