Short instructions that aim to help potential contributors.
-
Setup the Asciidoctor-revealjs plugin in development mode
-
Modify the slim templates in
templates/ -
Templates need to be compiled before being used, do so with:
bundle exec rake build
-
Then using the following command will render slides with your template changes baked in:
bundle exec asciidoctor-revealjs <source.adoc>
The next section will provide further help on how to use print statements or a debugger to assist development.
To understand what you have access to in templates you can inject some ruby.
With the slim templating system, this is done by prepending the lines with a dash (-) and inserting a ruby statement.
Two complementary approaches can be used to explore the context offered by asciidoctor through the template system:
-
logging on the command line via print-like statements
-
jump into the context through an interactive debugger
|
Note
|
Starting with v1.1.0 the slim templates are compiled to Ruby in order to use the same templates from Asciidoctor.js (Javascript / Node.js ecosystem). Don’t forget to recompile the templates if you make changes to them. This can be done by running: bundle exec rake build |
For example to see which attributes are available, you can print them by adding these lines in the .slim file of interest:
- puts @document.attributes.inspect - puts @attributes.inspect - puts @document.methods
Other generally useful ruby specific introspection:
- puts instance_variables - puts local_variables
One might find pp to produce better output (and in some cases not):
- require 'pp' - pp @document.attributes
Pry is a powerful debugger for ruby that features tab-completion. It is very useful to discover a complex object hierarchy like what asciidoctor offers.
In order to be dropped into the debugger at a specific point in a template simply add the following two lines in the relevant .slim template file:
- require 'pry' - binding.pry
Then run asciidoctor-revealjs from the command-line to generate your document and you’ll be dropped in the debugger:
$ bundle exec asciidoctor-revealjs examples/video.adoc
asciidoctor: WARNING: level-sections.adoc: line 29: section title out of sequence: expected level 2, got level 3
From: /home/olivier/src/asciidoc/asciidoctor-reveal.js/templates/slim/section.html.slim @ line 3 :
1: - hide_title = (title = self.title) == '!'
2: - require 'pry'
=> 3: - binding.pry
4: / parent section of vertical slides set
5: - if @level == 1 && !(subsections = sections).empty?
6: section
7: section id=(hide_title ? nil : @id) data-transition=(attr 'data-transition') data-transition-speed=(attr 'data-transition-speed') data-background=(attr 'data-background') data-background-size=(attr 'data-background-size') data-background-repeat=(attr 'data-background-repeat') data-background-transition=(attr 'data-background-transition')
8: - unless hide_title
[1] pry(#<Asciidoctor::Section>)>
Then using commands like the following allows you to explore interactively asciidoctor’s API and object model with syntax highlighting:
[1] pry(#<Asciidoctor::Section>)> @document
You can also query asciidoctor’s documentation:
[4] pry(#<Asciidoctor::Section>)> ? find_by
If you install the pry-byebug gem you get additional debugging capabilities.
See the gem’s documentation for details.
Since 1.1.0, templates are compiled. It is easier to inject the debug triggering statements and use the templates directly instead of debugging compiled templates. You can call the slim templates directly with:
bundle exec asciidoctor --trace -T templates/ examples/customcss.adoc
In order to help troubleshoot issues and test syntax improvements, some minimalist asciidoc test files are provided.
You can render the tests files and then load them in a browser and check if asciidoctor-revealjs behaves as expected.
Make sure to have a working version of asciidoctor-reveals this is usually
done with bundler:
bundle config --local github.https true bundle --path=.bundle/gems --binstubs=.bundle/.bin bundle exec rake build
Go to test/doctest folder and install reveal.js:
cd test/doctest/ git clone /~https://github.com/hakimel/reveal.js.git
From the project’s root directory:
bundle exec rake doctest::generate FORCE=yes
|
Note
|
Right now, doctest issue #12 means that the generated examples will not be pretty. |
You can open the generated .html in test/doctest/ in a Web browser.
The attr and attr? methods inherit by default. That means if they don’t find the attribute defined on the node, they look on the document.
You only want to enable inheritance if you intend to allow an attribute of the same name to be controlled globally. That might be good for configuring transitions. For instance:
= My Slides :transition-speed: fast == First Slide
However, there may be attributes that you don’t want to inherit. If that’s the case, you generally use the form:
attr('name', nil, false)
The second parameter value is the default attribute value, which is nil by default.
Relevant documentation: http://www.rubydoc.info/github/asciidoctor/asciidoctor/Asciidoctor%2FAbstractNode%3Aattr
Any non-trivial change should be integrated in master via a pull-request. This gives the community a chance to participate and helps write better code because it encourages people to review their own patches.
Pull requests should come from personal forks in order not the clutter the upstream repository.
Once a pull request is submitted, let it sit for 24-48 hours for small changes. If you get positive feedback you can merge before the sitting time frame. If you don’t get feedback, just merge after the sitting time frame.
Larger changes should sit longer at around a week. Positive feedback or no feedback should be handled like for small changes.
Breaking changes should sit until a prominent contributor comments on the changes.
Ping @mojavelinux and @obilodeau if necessary.
Remember that this is a slower moving project since people are not designing slides everyday. Well, for most people.
If you prepend "WIP" in front of your pull request we will understand that it is not complete and we will not merge it before you remove the WIP string.
This is useful to let people know that you are working on stuff. Branches are not that visible otherwise but pull requests are.
You might even be able to get some feedback early which could save you some time.
In order to test the Node package, you first need to build the converter into Javascript and create a tarball of the project.
$ bundle exec rake build:js $ npm pack
That last command will produce a file named asciidoctor-reveal.js-<version>.tgz in the working directory.
Then, create a test project adjacent to the clone of the asciidoctor-reveal.js repository:
$ mkdir test-project $ cd test-project
Now, install the dependencies from the tarball:
$ npm i --save ../asciidoctor-reveal.js/asciidoctor-reveal.js-<version>.tgz
|
Note
|
The relative portion of the last command is where you are installing the local asciidoctor-reveal.js version from.
|
Then proceed as documented in the README.adoc.
|
Warning
|
It is important to track Asciidoctor.js and opal versions together.
The opal used to compile our node package must match asciidoctor.js’s `opal requirement.
The former is specified in our package.json and the latter in the asciidoctor-revealjs.gemspec.
When you update one remember to update the other.
Versions known to work together can be found by looking at the Asciidoctor.js release notes, just replace <tag> with the asciidoctor.js release you are interested in: /~https://github.com/asciidoctor/asciidoctor.js/releases/tag/<tag>;.
|
Compile the converter:
$ bundle exec rake build
In a clean directory besides the asciidoctor-reveal.js repository, create the following Gemspec file:
source 'https://rubygems.org' gem 'asciidoctor-revealjs', :path => '../asciidoctor-reveal.js'
Then run:
$ bundle --path=.bundle/gems --binstubs=.bundle/.bin
-
Update the version in
lib/asciidoctor-revealjs/version.rbandpackage.json -
Update the changelog
-
Generate author list with:
git log <prev-version-tag>.. --format="%aN" --reverse | perl -e 'my %dedupe; while (<STDIN>) { print unless $dedupe{$_}++}' | sort
-
-
Prepare release commit
-
commit msg: Prepare %version% release
-
release commit (--allow-empty) msg: Release %version%
-
-
Tag the release commit
-
Annotated Tag msg: Version %version%
-
-
Push your changes (including the tag)
-
Make a release on github (from changelog and copy from previous releases)
-
Useful vim regex for AsciiDoc to Markdown:
:%s/{uri-issue}\d+\(\(\[#\d\+\)]\)/\1(https:\/\/github.com\/asciidoctor\/asciidoctor-reveal.js\/issues\/\2)/gc
-
-
Pushing the gem on rubygems.org:
$ bundle exec rake build $ gem build asciidoctor-revealjs.gemspec $ gem push asciidoctor-revealjs-X.Y.Z.gem
-
Check that the new version is available on rubygems.org
-
Generate the javascript version of the Ruby converter
$ bundle exec rake build:js
-
Test the node package (make sure you have
devDependenciesinstalled with:npm install):$ npm run test
-
Publish the node package on npm:
$ npm login # only required if not already authenticated $ npm publish
-
Check that the new version is available on npmjs.com
-
Update version in
lib/asciidoctor-revealjs/version.rbandpackage.json(+1 bugfix and append '-dev') and commit-
commit msg: Begin development on next release
-
-
Submit a PR upstream to sync the documentation on asciidoctor.org
We recommend tests to be run with a fresh install of all dependencies in a local folder that won’t affect your ruby install (a .bundle/ in this directory):
bundle --path=.bundle/gems --binstubs=.bundle/.bin
Then you can execute the tests with:
bundle exec rake doctest
However, if you have all dependencies properly installed this command should run the tests successfully:
rake doctest
Tests were bootstrapped by generating them from asciidoctor-doctest’s test corpus and current asciidoctor-revealjs' slim template engine. This is done using the following command:
bundle exec rake doctest:generate FORCE=y