Implement Static Defined Headers

[evangallup]

An issue we have run into recently when building a PDF from a large set of data is memory usage.

We can alleviate this issue by creating tables in smaller chunks of the data with something like the below

@table_data.each_slice(500).with_index do |batch, i|
  doc.table(batch, width: doc.bounds.width) do
    #styling
  end
end

After implementing the above our memory usage was lowered from ~2.5gb to about 600mb. Great, but it introduced an issue for us.

The formatting still works, we don't end up with random page breaks. This issue is that it breaks the ability to use the headers option, because after the first chunk of data the first line is no longer the actual header.

This PR implements a headers option which can be used like the below

header_data = [table_data.first]
table_data.each_slice(500).with_index do |batch, i|
  doc.table(batch, header: true, headers: header_data, width: doc.bounds.width) do
    # same styling as before
    # you can also independently style the header cells themselves
    headers.size = 8
    headers.borders = []
    headers.padding = [0, 5, 5, 0]

    # and the individual columns of the header
    headers.column(0).width = doc.bounds.width * 0.08

    # and the rows
    headers.row(0).font_style = :bold
  end
end

I'd like to get thoughts on this. I'm not sure if there is anything I'm missing here. I did try to generate the manual in this branch, but ran into some errors when doing so.

[gettalong]

How does headers interact with header? You mention that header should be set to true. In the code I can see that this means there is one header row. Shouldn't header be set to the number of rows in headers if the latter is used? I.e. that headers also automatically sets (and overrides) header?

[evangallup]

How does headers interact with header? You mention that header should be set to true. In the code I can see that this means there is one header row. Shouldn't header be set to the number of rows in headers if the latter is used? I.e. that headers also automatically sets (and overrides) header?

Yes, that's a good point and may be something that needs further documentation. I tried not to change the functionality of the header option directly, only adding the headers option will replace the headers on pages after the first. I tried to make that clear in my example, that the header should be included in both the main table data as the first row and specified in the headers option.