Skip to content
This repository has been archived by the owner on Jan 10, 2023. It is now read-only.

Latest commit

 

History

History
287 lines (176 loc) · 10.4 KB

CONTRIBUTING-CODE.adoc

File metadata and controls

287 lines (176 loc) · 10.4 KB
Raw

Contributing Code

This guide provides all the information you need to become a successful Asciidoctor PDF developer and code contributor! You’ll learn how to retrieve the code from GitHub, execute the tests, build and install the gem, and run the application with your local modifications.

Guidelines

To contribute code, fork the project on GitHub, hack away, and send a pull request with your proposed changes. All pull requests must include a) tests that verify the code change and b) an entry in the CHANGELOG.adoc file to document what changed. If a pull request is missing tests or a CHANGELOG entry, it will not be merged.

Feel free to use the issue tracker or Asciidoctor mailing list to provide feedback or suggestions in other ways.

Follow the instructions below to learn how to clone the source and run it from your local copy.

Development

Retrieve the Source Code

You can retrieve the source of Asciidoctor PDF in one of two ways:

  1. Clone the git repository

  2. Download a zip archive of the repository

Option 1: Fetch Using Git

If you want to clone the git repository, simply copy the GitHub repository URL and pass it to the git clone command:

$ git clone https://github.com/asciidoctor/asciidoctor-pdf

Next, change to the project directory:

$ cd asciidoctor-pdf

Option 2: Download the Archive

If you want to download a zip archive, click the Download Zip button on the right-hand side of the repository page on GitHub. Once the download finishes, extract the archive, open a console and change to that directory.

💡
 Instead of working out of the asciidoctor-pdf directory, you can simply add the absolute path of the bin directory to your PATH environment variable.

We’ll leverage the project configuration to install the necessary dependencies.

Install Dependencies

We recommend using RVM to manage the installation of Ruby you’ll use to build and develop the project.

$ rvm use 2.6

The dependencies needed to use Asciidoctor PDF are defined in the Gemfile at the root of the project. We can use Bundler to install the dependencies for us.

To check you have Bundler available, use the bundle command to query the installed version:

$ bundle --version

If it’s not installed, use the gem command to install it.

$ gem install bundler

Then use the bundle command with the --path option to install the project dependencies into the project:

$ bundle --path=.bundle/gems
📎
 You must call bundle from the project directory so that it can find the Gemfile.

Run the Tests

Tests are written using RSpec. To run the tests, simply invoke rspec via bundler.

$ bundle exec rspec

To disable tests that access the network, pass the -t ~network option:

$ bundle exec rspec -t ~network

Similarly, to disable the visual integration tests, pass the -t ~visual option:

$ bundle exec rspec -t ~visual

If a visual integration test fails, you can instruct the test suite to keep the files in the spec/output directory by setting the DEBUG environment variable:

$ DEBUG=true bundle exec rspec -t visual

If you want to see the name of each test as it is run, add the -fd option:

$ bundle exec rspec -fd

You can also use the provided Rake task (note the name difference):

$ bundle exec rake spec

Running tests using rspec directly gives you the advantage of being able to specify additional options.

To run a single test, you can filter by the name of the test. For example, to run all tests that pertain to failures, use:

$ bundle exec rspec -e fail

To run all tests that have wip in the name, use:

$ bundle exec rspec -e wip

You can also run all tests in a given file by passing the file’s path to rspec:

$ bundle exec rspec spec/toc_spec.rb

For a full list of options that rspec provides, run rspec -h.

Run the Application (optional)

Like with Bundler, you have to run the application from the project directory. Assuming all the required gems install properly, verify you can run the asciidoctor-pdf script using Ruby:

$ bundle exec asciidoctor-pdf -v

If you see the version of Asciidoctor PDF printed, you’re ready to use Asciidoctor PDF!

You can use the application to convert a document as follows:

$ bundle exec asciidoctor-pdf /path/to/sample.adoc

Install the Application (optional)

If you want to install the application globally so you can run it anywhere, use the following rake task:

$ bundle exec rake install

This task will package the gem and install it into your system gems.

If you want to install the gem using a separate command, first use the following rake task to build it:

$ rm -rf pkg
  bundle exec rake build

This task packages the application as a gem and writes it to the pkg directory. A message will be printed to the console telling you the exact filename. You can now use the gem install command to install it.

$ gem install pkg/*.gem

You’ll want to pay attention to which Ruby installation you are installing the gem into. If successful, the asciidoctor-pdf executable will be available on your PATH.

💡
 If you’re running Asciidoctor PDF in a Gradle build, follow these instructions to use the development version of Asciidoctor PDF.

Test a Pull Request

To test a pull request (PR), you first need to fetch the branch that contains the change and switch to it. The steps below are covered in detail in the GitHub help.

Let’s assume you want to test PR 955. Here’s how you fetch and switch to it:

$ git fetch origin pull/955/head:pr-955-review
  git checkout pr-955-review
❗
 Make sure you replace the number with the number of the PR you want to test.

In case any dependencies have changed, you should run the bundle command again:

$ bundle

Now you can run the application as modified by the PR:

$ bundle exec asciidoctor-pdf /path/to/sample.adoc

To switch back to master, just type:

$ git checkout master

In Your Application

If you’re using Asciidoctor PDF in your application, you can test against the code in the pull request using Bundler.

First, you need to find the origin URL and branch of the PR. You can find this information on the PR page.

Next, update the entry in your project’s Gemfile to point to the branch from which the pull request was originated.

Gemfile
source 'https://rubygems.org'

gem 'asciidoctor-pdf', github: '<username>/asciidoctor-pdf', branch: 'issue-864'

Then run Bundler to update the gems in your project:

$ rm -f Gemfile.lock
  bundle config --local github.https true
  bundle --path=.bundle/gems --binstubs=.bundle/.bin

Now you can run the development version of Asciidoctor PDF using:

$ bundle exec asciidoctor-pdf input.adoc

or

$ ./.bundle/.bin/asciidoctor-pdf input.adoc

These instructions work for testing any development version of Asciidoctor PDF directly from GitHub.

Generate Code Coverage Report

To generate a code coverage report when running tests using simplecov, set the COVERAGE environment variable as follows when running the tests:

$ COVERAGE=true bundle exec rake spec

You’ll see a total coverage score as well as a link to the HTML report in the output. The HTML report helps you understand which lines and branches were missed, if any.

Despite being fast, the downside of using simplecov is that it misses code branches. You can use deep-cover instead of simplecov to generate a more thorough report. To do so, first run bundle at least once with the COVERAGE environment variable set:

$ COVERAGE=true bundle

Then, set the COVERAGE environment variable to deep when running the tests:

$ COVERAGE=deep bundle exec rake spec

You’ll see a total coverage score, a detailed coverage report, and a link to HTML report in the output. The HTML report helps you understand which lines and branches were missed, if any.

Rebuild the Formatter Text Parser

The formatted text is first converted to a pseudo-HTML language, then converted from there into Prawn text fragments using a treetop parser. treetop is a Ruby-based parsing DSL based on parsing expression grammars. This strategy allows the converter to manipulate the formatted text without needing the know the internal details of how Prawn arranges text fragments. It also allows Asciidoctor to behave in a consistent manner, since some of the inline parsing in Asciidoctor assumes that the converter is generating an SGML-based language like HTML or DocBook.

The parsing expression grammar is defined in the source file lib/asciidoctor/pdf/formatted_text/parser.treetop. If you make a change to this file, you must regenerate the parser, which is defined in the source file lib/asciidoctor/pdf/formatted_text/parser.rb. (Don’t modify the generated parser directly).

Use the following command to regenerate the parser:

bundle exec tt lib/asciidoctor/pdf/formatted_text/parser.treetop

Then look for any places that a type is mixed into an object multiple times and remove the duplicate. Finally, you then need to commit both files.