Add initial asciidoctor-spring-backend code

Author: philwebb

.eslintrc

@@ -0,0 +1,3 @@
+{
+  "extends": ["eslint:recommended", "standard", "prettier"]
+}

.prettierignore

@@ -0,0 +1,7 @@
+/*
+!src
+*.java
+highlight.js
+src/test/resources/**/*.html
+src/test/maven/target
+src/test/gradle/build

.prettierrc.json

@@ -0,0 +1 @@
+{}

.stylelintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": "stylelint-config-standard"
+}

CODE_OF_CONDUCT.adoc

@@ -0,0 +1,44 @@
+= Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of fostering an open
+and welcoming community, we pledge to respect all people who contribute through reporting
+issues, posting feature requests, updating documentation, submitting pull requests or
+patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for
+everyone, regardless of level of experience, gender, gender identity and expression,
+sexual orientation, disability, personal appearance, body size, race, ethnicity, age,
+religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic addresses,
+  without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments,
+commits, code, wiki edits, issues, and other contributions that are not aligned to this
+Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors
+that they deem inappropriate, threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to fairly and
+consistently applying these principles to every aspect of managing this project. Project
+maintainers who do not follow or enforce the Code of Conduct may be permanently removed
+from the project team.
+
+This Code of Conduct applies both within project spaces and in public spaces when an
+individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by
+contacting a project maintainer at spring-code-of-conduct@pivotal.io . All complaints will
+be reviewed and investigated and will result in a response that is deemed necessary and
+appropriate to the circumstances. Maintainers are obligated to maintain confidentiality
+with regard to the reporter of an incident.
+
+This Code of Conduct is adapted from the
+https://contributor-covenant.org[Contributor Covenant], version 1.3.0, available at
+https://contributor-covenant.org/version/1/3/0/[contributor-covenant.org/version/1/3/0/]

CONTRIBUTING.adoc

@@ -0,0 +1,222 @@
+= Contributing to Asciidoctor Spring Backends
+
+Unless otherwise noted, code in this project is released under the Apache 2.0 license.
+If you would like to contribute something, or want to hack on the code this document should help you get started.
+
+
+== Code of Conduct
+This project adheres to the Contributor Covenant link:CODE_OF_CONDUCT.adoc[code of conduct].
+By participating, you are expected to uphold this code. Please report unacceptable behavior to spring-code-of-conduct@pivotal.io.
+
+
+
+== Building from Source
+Source can be built from the command line using https://gradle.org[Gradle] on JDK 1.8 or above.
+We include https://docs.gradle.org/current/userguide/gradle_wrapper.html[Gradle's wrapper scripts] (`./gradlew` or `gradlew.bat`) that you can run rather than needing to install Gradle locally.
+
+The project can be built from the root directory using the standard Gradle command:
+
+[indent=0]
+----
+	$ ./gradlew build
+----
+
+
+
+== Working with the Code
+There are quite a few moving parts to this project and a lot of different technologies involved.
+The project can broadly be split into two parts:
+
+. An AsciidoctorJ compatible extension providing the backends
+. A set of web assets (CSS & Javascript) used by the HTML generated by the backend.
+
+
+
+=== AsciidoctorJ Backend
+The AsciidoctorJ backend is Ruby and Java code that provides a https://www.rubydoc.info/gems/asciidoctor/Asciidoctor/Converter[Asciidoctor::Converter] implementation.
+
+
+
+==== Ruby Code
+The main converter implementation is written in Ruby.
+You can find the code in the link:src/main/ruby[`src/main/ruby`] folder.
+
+The code delegates to the standard `html5` converter, but changes a few areas to give us the HTML that we need.
+It also writes the CSS, Javascript and Images to the output directory.
+
+The code needs to be packaged as a Gem so that it can be picked up by AsciidoctorJ.
+
+This means that the Jar needs to have the following layout:
+
+----
+specifications/
+  asciidoctor-spring-backends-0.0.0.gemspec
+gems/
+  asciidoctor-spring-backends-0.0.0/
+    lib/
+      asciidoctor-spring-backends
+    data/
+----
+
+NOTE: The version number of the Gem isn't really important in our case so we set it to `0.0.0`.
+
+If you need to edit the `gemspec` file you can find it in link:src/main/ruby[`src/main/gemspec`].
+
+AsciidoctorJ won't find the converter from the Gem alone, it needs to be told that it's a `requireLibrary`.
+This is done with the `SpringBackendsExtensionRegistry` class which is registered using `META-INF/services`.
+
+
+
+==== Java Code
+The code folding and chomping features are implemented in Java.
+You can find the code in link:src/main/java[src/main/java].
+
+There's a `convert_listing_content` method in the Ruby code that uses JRuby features to call the `ListingContentConverters` class.
+The `ListingContentConverters` class is responsible for taking an Asciidoctor node and returning its content in a potentially modified form.
+There a bit of adapter logic needed to convert the `RubyObject`, but nothing too onerous.
+
+All the project tests are also written in Java.
+There's a mixture of both unit tests and integration tests.
+They're available at link:src/test/java[src/test/java].
+
+
+
+==== Hacking on the Ruby Code
+If you want to iterate quickly on the Ruby code it's often easier to run it directly rather the using the Gradle build.
+You can do this by using the `asciidoctor` CLI command.
+
+[source,shell]
+----
+$ asciidoctor --trace -r ./src/main/ruby/lib/asciidoctor-spring-backends.rb -b spring-html -D build/converted-asciidoc/ src/test/resources/standard.adoc
+----
+
+NOTE: Using asciidoctor directly means that JRuby doesn't run.
+Java calls will not occur and `ListingContentConverters` features will not apply.
+
+
+
+=== Web Assets
+Web assets are bundled up inside the Jar and copied out by the Ruby converter.
+The following web assets are used:
+
+* `site.css` file in the `/css` folder.
+* `setup.js` and `site.js` files in the `/js` folder.
+* Images in the `/img` folder.
+
+
+
+==== Build
+The web assets are all build using GulpJS which is invoked via NPM from the Gradle build.
+You can also build the web assets directly using the gulp CLI.
+
+Install it using NPM:
+
+[source,shell]
+----
+$ npm install
+----
+
+Then run it with the `build` target:
+
+[source,shell]
+----
+$ gulp build
+----
+
+The gulp build will do the usual front-end related tasks such as minification and linting.
+Take a look `gulpfile.js` if you want to see the exact details.
+
+
+
+==== Javascript
+There are two javascript assets produced by the build:
+
+* `setup.js` provides any initial setup and is loaded with a regular `<script>` element.
+* `site.js` provides the majority of the Javascript and is loaded with a `<script async>` element.
+
+The source code used to build these files is in link:src/main/js/setup[`src/main/js/setup`] and link:src/main/js/setup[`src/main/js/site`] respectively.
+
+TIP: The `setup.js` file will block page loading and as such should only be used for critical functionality.
+For example, it includes the dark theme switching logic so that the page doesn't flash when loading.
+
+The following files are used to create the `setup.js` file:
+
+* `layout.js` - Adds a `js` class to the `html` element for CSS to use for Javascript detection.
+* `switchtheme.js` - Provides theme switcher logic
+
+The following files are used to create the `site.js` file:
+
+* `codetools.js` - Provides the copy and fold/unfold buttons
+* `highlight.js` - Provide a HighlightJS bundle
+* `tabs.js` - Provides tab switching support
+* `toc.js` - Updates the table of contents when scrolling
+
+
+
+==== CSS
+The single `site.css` file is build from a number of smaller CSS files.
+CSS files can be found in link:src/main/css[`src/main/css`].
+PostCSS is used to follow `@Import` declarations and create a single file.
+
+Although it's a little overkill for this project, CSS files are organized using the https://www.freecodecamp.org/news/managing-large-s-css-projects-using-the-inverted-triangle-architecture-3c03e4b1e6df/[inverted triangle] architecture.
+
+
+----
+--------------  _
+\            / __ settings   : (settings.css, settings-dark.css)
+ \          / ___ tools      : (none)
+  \        / ____ generic    : (generic.css)
+   \      / _____ elements   : (elements.css)
+    \    / ______ objects    : (none)
+     \  / _______ components : (components.css)
+      \/ _________utilities  : (none)
+----
+
+
+
+===== CSS Variables
+CSS variables are used extensively for colors and variable styling.
+The `settings.css` file contains initial settings and `settings-dark.css` provides dark-mode overrides.
+
+Variables are usually scoped to a specific area and then reference a more generic value.
+For example, `--toc-font-color` is the font color of the TOC.
+It has the value `var(--body-font-color)` which references the general body font color.
+
+
+
+==== Images
+Images are available in the link:src/main/img[`src/main/img`] folder.
+It's best to use SVG images as much as possible.
+
+A single `octicons-16.svg` file provides all the 16x16 icons used by the CSS.
+This file contains a subset of the icons from https://github.com/primer/octicons.
+
+
+
+==== Hacking on the web assets
+If you need to work on the web assets you can run the following Gradle task:
+
+[source,shell]
+----
+$ ./gradlew dev
+----
+
+Alternatively you can generate some test HTML and the run `gulp` directly:
+
+[source,shell]
+----
+$ ./gradlew convertTestAsciidoc
+$ gulp dev
+----
+
+NOTE: The `convertTestAsciidoc` Gradle task will convert the contents of the link:src/test/asciidoc[`src/test/asciidoc`] directory.
+
+The `dev` task will start a server at `http://localhost:8080` and watch the source files for changes.
+Saving any source file will trigger a rebuild and "live reload".
+
+
+
+=== Formatting
+Java, Javascipt and CSS files can be formatted by running `./gradlew format`.
+Java files are formatted using `spring-javaformat`.
+Other files are formatted using https://prettier.io/[prettier].