На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- Фонд облачных вычислений (CNCF)
- Технический писатель:
- фелой
- Название проекта:
- Обновите способ предоставления ссылок на API на веб-сайте Kubernetes.
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание Проекта
В настоящее время ссылки на API Kubernetes представляют собой большие HTML-документы , созданные на основе спецификаций Swagger с помощью скриптов , размещенных за пределами репозитория веб-сайта , а затем добавленные в этот репозиторий веб-сайта.
С другой стороны, веб-сайт документации Kubernetes создан с помощью Hugo на основе документации, написанной в формате Markdown в репозитории веб-сайта, с использованием темы Docsy Hugo .
Цель этого проекта — интегрировать создание ссылок API Kubernetes в процесс создания веб-сайта документации.
В частности, мы сосредоточимся на шорткоде swaggerui , обертке вокруг swagger-ui , предоставляемом темой Docsy Hugo, а также на конкретных инструментах, позволяющих вставлять части спецификации API в поток документации Kubernetes.
Потребуются специальные инструменты, поскольку swagger-ui способен выводить полную спецификацию, описанную в файле swagger, а не ее части (см. 8) . API Kubernetes слишком велик, чтобы его можно было отобразить только в одной части (пример вывода) . Мы рассмотрим два подхода:
Первый подход — создать несколько файлов swagger, по одному для каждой группы API Kubernetes (core/v1, apps/v1,...) из источников, доступных по адресу (10) , и использовать эти файлы в качестве входных кодов сортировки swaggerui в определенных местах Kubernetes. сайт документации,
Второй подход заключается в создании инструмента, который получает на входе полный файл Swagger API Kubernetes, найденный в (11) , и выводит новый файл Swagger для определенной конечной точки или ограниченного числа конечных точек, а также связанных с ним ресурсов и определений, а затем использует эти файлы swagger в качестве входных данных коротких кодов swaggerui в определенных местах веб-сайта документации Kubernetes.
Поскольку источники спецификаций (10 и 11) находятся в других репозиториях, а не в источниках документации, нам нужно будет найти способ автоматического обновления их в репозитории документации при их изменении.
Поскольку документация Kubernetes доступна на разных языках, мы уделим особое внимание возможности публикации переводов справочника Kubernetes API.