Add documentation about document configuration

[sowenjub]

Echoes #802.

I had seen the greeter example in the docs but missed the comment on the document method. I thought it might be helpful to include it in the example as well.

[pointlessone]

Thank you for your contribution.

Could you please make Rubocop happy?

[sowenjub]

Sure, done.

[pointlessone]

Great!

Could you please rebase your branch on master and squash the commits?

[sowenjub]

Not sure I did this right

[pointlessone]

Yeah, doesn't look right. I'll do it locally and merge it later. Or let me know if you need help if you want to do it yourself.

[sowenjub]

If you don't mind, help me do it.
I ran git rebase master patch-1 and then git rebase -i fdf0445775e4f3ef5f3c674101cda64b7a4ef4ed, squashing only my 2nd commit.

[pointlessone]

The gist of it is right. However, you rebased on your master. It's not the same as Prawn master.

There are many way of doing this, as often. So I'll describe what I do. You may find a slightly different approach if you google or adapt this to what you're familiar with but in the end it should be the same.

GitHub is not very convenient for keeping up with the upstream repos. I usually add another remote to my local repo:

git remote add upstream git@github.com:prawnpdf/prawn.git

Then I make sure it's up to date:

git pull upstream

Then I make sure my local master is in sync with the upstream, or convenience:

git checkout master
git rebase upstream/master

Then rebase your branch on top of that. Technically, you can rebase on top of upstream/master directly but this approach lets you have your own copy of the history easily available.

git checkout patch-1 # your PR branch
git rebase -i master

Then (force) push your rebase branch to GH.

[sowenjub]

Not sure what happened, I ended up on a detached head.

After git rebase -i master I got

Auto-merging spec/prawn_manual_spec.rb
CONFLICT (content): Merge conflict in spec/prawn_manual_spec.rb
Auto-merging prawn.gemspec
CONFLICT (content): Merge conflict in prawn.gemspec
Auto-merging lib/prawn/images/png.rb
Auto-merging .rubocop.yml
error: could not apply 06f60288... Update RuboCop
Resolve all conflicts manually, mark them as resolved with
"git add/rm <conflicted_files>", then run "git rebase --continue".
You can instead skip this commit: run "git rebase --skip".
To abort and get back to the state before "git rebase", run "git rebase --abort".
Could not apply 06f60288... Update RuboCop

I went on a fixed the conflicts, added the files, git rebase --continue and got

The previous cherry-pick is now empty, possibly due to conflict resolution.
If you wish to commit it anyway, use:

    git commit --allow-empty

Otherwise, please use 'git reset'
interactive rebase in progress; onto b3f04e18
Last commands done (3 commands done):
   pick 06f60288 Update RuboCop
   pick 5cb8bbbc Fix manual spec
Next commands to do (4 remaining commands):
   pick df43d0e4 Update Rubocop
   pick 7f07bb8c Fix RuboCop requires
You are currently rebasing branch 'patch-1' on 'b3f04e18'.

nothing to commit, working tree clean
Could not apply 5cb8bbbc... Fix manual spec

Not sure what to do, I tried git commit --allow-emptyand got on [detached HEAD 29f589e8]

[pointlessone]

This happens when your next commit in the queue has no changes. Usually this means that the base branch already contains the changes. Git stops because your commit is not only code changes. It's also a commit message which might contain important information.

You have two choices:

• Skip commit
• Add and empty commit

In most cases it's OK to skip commit. You do this by running git rebase --skip. This will also continue the rebase.

If you want to preserve commit message even when there's no changes to the code you need to run git commit --allow-empty. This will add a commit that only has a commit message but no code changes. You end up on a commit that has no branch attached to it. That's why it's called detached HEAD. You can continue rebase with git rebase --continue.

I suggest you finish this rebase and then try once more to remove the empty commit.

[sowenjub]

That should do it, let me know.
Thanks a lot for taking the time to explain things @pointlessone, much appreciated.

[pointlessone]

Thank you!