Документация по методу Jenkinfile Libary

Как добавить документацию к вызовам API?

Я создал следующую библиотечную функцию в SCM. Это связано с помощью метода Дженкинса, и это прекрасно работает. Теперь мне нужно добавить документацию, чтобы она отображалась в разделе */pipeline-syntax/globals. В моем vars/sayHello.groovy У меня есть следующая подпись:

#!groovy
/**
 *  this says hello
 * @param name to greet
**/
def call(String name) {

Я пробовал это с синтаксисом Javadoc, но, похоже, не является решением. Что я должен сделать, чтобы получить документацию в представлении Jenkins? Например:

1 ответ

Решение

Это на самом деле довольно неясно, и вы должны покопаться, чтобы найти его, а затем экспериментировать, чтобы это заработало. Если вы посмотрите документацию для разделяемых библиотек и прокрутите вниз до структуры каталогов, то увидите строку, которая говорит:

Базовое имя каждого файла.groovy должно быть идентификатором Groovy (~ Java), обычно camelCased. Соответствующий файл.txt, если он есть, может содержать документацию, обработанную с помощью сконфигурированного системного форматера разметки (в действительности это может быть HTML, Markdown и т. Д., Хотя требуется расширение txt).

Это означает, что вам нужен соответствующий vars/sayHello.txt, Как только вы создадите этот файл, он будет использован для создания документации в том месте, где вы его ищете (https://<jenkins_host>/job/<your_job>/pipeline-syntax/globals). Как указано в документации, вы можете использовать в файле языки разметки, такие как Markdown или HTML, но расширения должны быть .txtи оно должно иметь одинаковое базовое имя.

Здесь есть два дополнительных предостережения. Во-первых, вы должны запустить хотя бы один конвейер с загруженной в него разделяемой библиотекой, прежде чем появится документация. Второй так же неясен, как и оригинальные инструкции о том, как это сделать: вам нужно перезапустить (или даже перезагрузить) экземпляр Jenkins.

Как только все эти требования будут выполнены (и я честно застрял на требовании перезапуска, пока пользователь "missedone" не упомянул его мне в моем трекере проблем Github для моих библиотек Jenkins), тогда появится документация, которую вы хотите.

Еще одно замечание: эти файлы документации могут быть символической ссылкой на другое место в вашей библиотеке (например, sayHello.txt --> ../docs/sayHello.md), как я это делаю, и это работает.

Другие вопросы по тегам