Add a macro to document a declared dependency

[philwebb]

We often need to guide users on how they can declare a dependency that they might need to consume. Often this involves both Maven and Gradle configuration and sometimes extra repository definitions. Some examples:

• https://docs.spring.io/spring-boot/gradle-plugin/getting-started.html
• https://docs.spring.io/spring-security/reference/servlet/saml2/login/overview.html#servlet-saml2login-minimaldependencies

It would be helpful if we could simplify this markup using a macro.

Initial brainstorming on syntax could be something like dependency::<groupid>:<artifactid>[:version][]. With additional options to influence the format and options. E.g.:

dependency::org.springframework:spring-core:123[]
dependency::org.springframework:spring-core[]
dependency::org.springframework:spring-core[format=gradle]
dependency::org.springframework:spring-core[format=maven]
dependency::org.springframework.security:spring-security-saml2-service-provider[repo=https://build.shibboleth.net/maven/releases/]

Ideally the repositories section would make use of code folding.

[rwinch]

I'm going to work on an MVP first, but taking notes as I work on this:

• We should support BOMs / platforms
• Repositories (some repos should only be releases, others only snapshots, etc)
• Optionally only doing Maven or Gradle
• We should support multiple dependencies (which might imply a different syntax?)
• We should support scopes (e.g. spring-test is a test dependency)
• We should support excludes
• Possible feature...(optional) validation of the dependency existing? Another option for this might be to have some standard way to have a build.gradle and pom.xml files that have all the dependencies that can be included and the extension lets you specify which depenencies should be added from the standard file (it's like a tag but for dependencides). This would allow the standard Maven/Gradle build to validate the dependencies exist.

[rwinch]

After talking over all the use cases that we will need to cover with @philwebb , we decided that this ends up being a pretty complex extension where we might not be getting the value we were looking for. I'm going to leave this open, but at the moment it isn't planned. I've got the simple example working in this branch in case we want to come back to it https://github.com/rwinch/asciidoctor-extensions/tree/depencency-macro

Worth mentioning that this ends up being kind of similar to the include-code macro if we were externalizing it as outlined in Possible feature in my previous comment