Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jenkins-infra/asciidoctor-jenkins-extensions

Extensions to asciidoctor syntax for Jenkins-related materials
https://github.com/jenkins-infra/asciidoctor-jenkins-extensions

jenkins ruby ruby-gem

Last synced: 3 months ago
JSON representation

Extensions to asciidoctor syntax for Jenkins-related materials

Awesome Lists containing this project

README 

        
= Asciidoctor::Jenkins::Extensions



image::https://ci.jenkins.io/job/Infra/job/asciidoctor-jenkins-extensions/job/main/badge/icon["Build status", link="https://ci.jenkins.io/job/Infra/job/asciidoctor-jenkins-extensions/job/main"]



This gem is a collection of Asciidoctor extensions which enable more advanced

formatting in Jenkins-related content.



== Installation



Add this line to your application's Gemfile:



[source,ruby]

----

gem 'asciidoctor-jenkins-extensions'

----



And then execute:



    $ bundle



Or install it yourself as:



    $ gem install asciidoctor-jenkins-extensions



== Usage



Using this gem inside of an existing Asciidoctor-based project is as

straight-forward as requiring `asciidoctor/jenkins/extensions`, for example:



[source,ruby]

----

require 'asciidoctor/jenkins/extensions'

----



In link:http://awestruct.org[Awestruct]-based projects, this `require`

statement should go in `_ext/pipeline.rb`.



=== [pipeline] block



An extension to Asciidoctor syntax adds the `[pipeline]` block for including

link:https://jenkins.io/doc/book/pipeline[Pipeline] code. This block supports

both *Declarative Pipeline* and *Pipeline Script* syntax. For example:



[source, asciidoc]

--

[pipeline]

----

// Script //

node {

    stage('Build') {

      checkout scm

      // Install dependencies

      sh 'npm install'

    }

}



// Declarative //

pipeline {

    agent docker: 'node:6.3'

    stages {

        stage('Build') {

            sh 'npm install'

        }

    }

}

----

--



This `pipeline` block will _prefer_ the Declarative Pipeline syntax when

rendering, and provide a link for toggling the Scripted Pipeline.



The `// Declarative //` or `// Script //` delimiters are *MANDATORY*, even when

defining a `[pipeline]` block with only one syntax supported. These delimiters

instruct the extension on how to render the given code.



=== the plugin macro



The `plugin` inline macro can be used to link to plugins on the plugins index

at https://plugins.jenkins.io/.



Example:



[source, asciidoc]

----

plugin:git[The Git Plugin]

----



=== jenkinsdoc/staplerdoc/javadoc macros



The `jenkinsdoc` inline macro can be used to link to the Jenkins Javadoc at https://javadoc.jenkins.io/.



It supports a variety of different syntaxes. For classes in Jenkins core:



* `jenkinsdoc:hudson.scm.SCM[]` links to the full URL for the class in Jenkins core.

* `jenkinsdoc:hudson.scm.SCM#all()[]` links to the full URL for the class in Jenkins core, and includes a fragment.

* `jenkinsdoc:SCM[]` links to the `/byShortName` URL for the class in Jenkins core. Due to the redirect, fragments won't work here.



By default, all of these use the class name as label, but that can be customized if necessary by providing an alternative label between the square brackets.



[source, asciidoc]

----

jenkinsdoc:hudson.scm.SCM#all()[a list of all known SCM implementations]

----



For classes in plugins, the plugin's name (`artifactId`) is put before the class name and separated by colon:



* `jenkinsdoc:git:hudson.plugins.git.GitSCM[]` links to the full URL for the class in the git plugin.

* `jenkinsdoc:git:hudson.plugins.git.GitSCM#getRepositories--[]` links to the full URL for the class in the git plugin, and includes a fragment.



These use a similar default label if none is set, but it also specified which plugin the class is in. For the previous example, that label would be _hudson.plugins.git.GitSCM in git_.



Two other inline macros, `staplerdoc` and `javadoc` exist and link to the Stapler API documentation and Java API documentation, respectively.

These do not support the form of `jenkinsci` that only requires the short name, but otherwise work the same way. Examples:



[source, asciidoc]

----

javadoc:java.io.File#pathSeparator[the path separator]

staplerdoc:org.kohsuke.stapler.AncestorInPath[]

----



=== Other macros (jep/jira/security)



See [examples](./examples).



== Development



After checking out the repo, run `bin/setup` to install dependencies. You can

also run `bin/console` for an interactive prompt that will allow you to

experiment.



To install this gem onto your local machine, run `bundle exec rake install`. To

release a new version, update the version number in `version.rb`, and then run

`bundle exec rake release`, which will create a git tag for the version, push

git commits and tags, and push the `.gem` file to https://rubygems.org[rubygems.org].



=== Acceptance Tests



In order to make testing of extensions easier, there is a bit of support for

live-page Asciidoc rendering with extensions live-reloaded on each page load.



In the `examples/` directory you will find sample `.adoc` files which serve as

test files for rendering with Asciidoctor and these extensions. To run the test

server, assuming you have already executed `bundle install`, run:



[source]

----

shotgun

----



And then navigate to link:http://localhost:9393/[localhost:9393]