Use https://github.com/google/vimdoc for helpfile generation

[stellarhoof]

Manually crafting vim helpfiles is cumbersome and hard to maintain, This
can lead to outdated helpfiles and inconsistent formatting.

vimdoc, as with all software, is not perfect. Its automation comes at
the price of buying into the rigidity of the formatting it provides and
it many cases it's not clear how to acomplish something except through
trial and error. The documentation is lacking in that respect. In my
musings I've found these some things vimdoc does not handle (not
exhaustive):

• Automatic generation of mapping documentation
• Validation of settings, commands, ... when using their
  corresponding directives (@setting(), @command(), ...)
• Interspersing documentation in generated sections. For example,
  arbitrary blocks of documentation in between commands.

I still think that despite its shortcomings, vimdoc can potentially save
precious time to developers of the plugin, thus lowering the barrier to
contributions.

Fixes #128

[stellarhoof]

I've got also a fix to #125 ready for pull request that depends on this one.

[jez]

Maybe I’m old school, but what’s the value to auto-generating a help file? I’m concerned because: - I’ve seen few projects that do use one, - it introduces complexity in the form of a build step, - the current help file and readme seem to suffice. I see that your main point is that manually creating help files is cumbersome and hard to maintain. While it may be a new syntax (Vim helpfile vs Markdown), it’s useful to know what helpfiles are strong and weak at to write idiomatic documentation. With regard to maintenance, my hope is that code review is sufficient to verify that documentation is updated at the same time as the code is changed. Of course, I’m relatively inactive with this plugin these days. I’d defer to the other maintainers if they think this will be a useful tool going forward.

…

On Sat, Dec 9, 2017 at 7:45 PM Alejandro Hernandez ***@***.***> wrote: I've got also a fix to #125 <#125> ready for pull request that depends on this one. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#129 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFSaVBOqonQNZA9JteNMTrV2_hGkVFabks5s-1PbgaJpZM4Q8MMN> .

[stellarhoof]

While it may be a new syntax (Vim helpfile vs Markdown), it’s useful to
know what helpfiles are strong and weak at to write idiomatic
documentation.

I'm not quite sure what you mean here

Requiring to install a dependency to build the helpfile does create a barrier to contribution, and I agree it's simpler to manage it manually. What worries me is that the docs get out of sync, forcing the users to inspect the code as the source of truth. Let's hope code review is indeed sufficient if the maintainers don't decide to use this.

[rdnetto]

I'm ambivalent about this - it looks like it would force us to be more consistent about our documentation, which is good, but it's effectively introducing a new syntax. I also dislike how much noise its adding to the source code, which makes it harder to identify the actual code.

I'm not going to veto this if someone is really keen to see it merged, but my preference would be to just stick with regular helpfiles. If we are going to generate these, then I'd insist on having a check in CI to make sure they remain in sync.

[stellarhoof]

Closing this then. If the maintainers want it back they can reopen