HACKING.adoc in asciidoctor-revealjs-1.0.4 vs HACKING.adoc in asciidoctor-revealjs-1.1.0

- old
+ new

@@ -4,18 +4,27 @@ Short instructions that aim to help potential contributors. == Inspect the template system - 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 +-- + === Print debugging information For example to see which attributes are available, you can print them by adding these lines in the `.slim` file of interest: ---- @@ -43,26 +52,25 @@ 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. ==== Initial Setup - gem install pry + bundle --path=.bundle/gems --binstubs=.bundle/.bin ==== Usage 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 from the command-line to generate your document and you'll be dropped in the debugger: +Then run `asciidoctor-revealjs` from the command-line to generate your document and you'll be dropped in the debugger: ---- -$ make -asciidoctor -T templates/slim -b revealjs test/level-sections.adoc +$ 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) == '!' @@ -83,65 +91,63 @@ 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: + +// TODO it's still not clear whether `-r slim-htag` is required right now (#153) + + bundle exec asciidoctor --trace -T templates/ examples/customcss.adoc + === References * https://github.com/asciidoctor/asciidoctor.org/issues/80#issuecomment-145698579 * http://pryrepl.org/ * http://discuss.asciidoctor.org/Interactively-debugging-a-template-with-a-REPL-td4498.html -== Tests +== Manual Tests 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-reveal.js` behaves as expected. +You can render the tests files and then load them in a browser and check if `asciidoctor-revealjs` behaves as expected. === Initial Setup 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/` folder and install `reveal.js`: +Go to `test/output/slim/` folder and install `reveal.js`: - cd test/ + cd test/output/slim/ git clone https://github.com/hakimel/reveal.js.git === Render tests into .html From the project's root directory: - make + bundle exec rake generate FORCE=yes === Open rendered files -You can open the generated `.html` in a Web browser. -For convenience the following command will open the last modified file: +NOTE: Right now, https://github.com/asciidoctor/asciidoctor-doctest/issues/12[doctest issue #12] means that the generated examples will not be pretty. - make open +You can open the generated `.html` in `test/output/slim/` in a Web browser. -Additionally, if you want to test with a minimalist web server: - make serve +== Asciidoctor API's gotchas -The server is running in the foreground and needs `Ctrl-C` to be killed. +=== Attribute inheritence -== Jade templates - -Jade templates are used by AsciidocFX. Since they are separate they might be -out of sync with our asciidoctor's slim templates. - -To test the jade templates, install AsciidocFX and copy the jade templates -over to AsciidocFX's `conf/slide/templates/revealjs/` directory. Then use -AsciidocFX to render the slides. - - -== Attribute inheritence - 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: @@ -197,36 +203,61 @@ You can apply that label to a pull request that is complete and ready for review. Makes triaging easier. - == Node package === Test a local asciidoctor-reveal.js version -In order to test the Node package, you need to create a test project adjacent to the clone of the `asciidoctor-reveal.js` repository: +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:converter:opal + $ npm run build + $ 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 [.path]_asciidoctor-reveal.js_ repository: + $ mkdir test-project $ cd test-project -Now, install the dependencies. +Now, install the dependencies from the tarball: -WARNING: It is important to track `Asciidoctor.js`, `Asciidoctor-template.js` and `bestikk-opal-compiler` versions all together. + $ 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`. + +=== Upgrade Asciidoctor.js version + +WARNING: It is important to track `Asciidoctor.js` and `bestikk-opal-compiler` versions together. The `opal-compiler` used to compile our node package must match `asciidoctor.js` `opal-runtime`. -The first one is explicitly installed by users on install and the two later are specified in our `package.json`. -When you update one remember to update the others. +The former is explicitly installed by users on install and the later is specified in our `package.json`. +When you update one remember to update the other. Versions known to work together can be found here, just replace <tag> with the `asciidoctor.js` release you are interested in: https://github.com/asciidoctor/asciidoctor.js/blob/<tag>/package.json - $ npm i --save asciidoctor.js@1.5.5-5 - $ npm i --save ../asciidoctor-reveal.js +== RubyGem package -NOTE: The relative portion of the last command is where you are installing the local `asciidoctor-reveal.js` version from. +=== Test a local asciidoctor-revealjs version -Then proceed as documented in the `README.adoc`. +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 + + == Release process . Update the version in `lib/asciidoctor-revealjs/version.rb` and `package.json` . Update the changelog ** Generate author list with: @@ -240,22 +271,56 @@ ** Annotated Tag msg: Version %version% . Push your changes (including the tag) . Make a release on github (from changelog and copy from previous releases) . 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 https://rubygems.org/gems/asciidoctor-revealjs[rubygems.org] +. Generate a compatible version of the Ruby converter (using opal mode) ++ + $ bundle exec rake build:converter:opal + . Build the node package (make sure you have `devDependencies` installed with: `npm install`): + $ npm run build . Publish the node package on npm: + - $ npm login + $ npm login # only required if not already authenticated $ npm publish . Check that the new version is available on https://www.npmjs.com/package/asciidoctor-reveal.js[npmjs.com] . Update version in `lib/asciidoctor-revealjs/version.rb` and `package.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 +** Modify this page: https://github.com/asciidoctor/asciidoctor.org/edit/master/docs/asciidoctor-revealjs.adoc +== Ruby and asciidoctor-doctest tests + +=== Running tests + +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 + +=== Generating HTML test target + +Tests were bootstrapped by https://github.com/asciidoctor/asciidoctor-doctest/#generate-examples[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 + +=== Custom tests + +Files in the `examples/` directory are used as tests. +Resulting slides are kept in `test/doctest/`.