Документация по методу 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
), как я это делаю, и это работает.