Generate more of the documentation with asciidoc and automate more

[jonahgraham]

• Migrate all getting_started from html to adoc
• Document (in README.md) notes on migrating html to adoc
• Reorganize generation of adoc slightly so that
  • all directories can be generates at once
  • output suffix changed to htm so that migrated files
    exist at the same URL on help.eclipse.org
• Add generation to the cleanliness checks to ensure that the
  html matches adoc
• Manage the adoc headers with a script as that is a large section
  of copy-pasted code on each adoc file (see README + adoc-headers.txt)
• Move maven version info to pluginManagement (consistency with other
  maven plug-ins)
• New profile "asciidoc-auto-refresh" which will auto build the
  files as edited.

Prerequisite of #992

[jonahgraham]

Some additional notes.

• by generating the HTML the docs are browsable, for example Tutorial entry point (from CDT) and the same file in my PR (on my fork) is here
• Using the links in the above bullet you can compare before and after the conversion to adoc
• I have made sure that the adoc browsing in github still works (see for example this file)
• Biggest issue I have is that everything is squished a little too much because original HTML used <br> liberally to vertically space content, but the adoc doesn't and relies on the css, which has 0 padding on items such as <li>:

  cdt/doc/org.eclipse.cdt.doc.user/help.css

  Line 29 in 39ee2ed

  li { margin-top: 0; margin-bottom: 0 }

@jld01 When you contributed the adoc work you added to help.css. Did you manually craft that css yourself, or was it the result of running asciidoctor one time and then adding it to help.css? I will probably create a separate css for the adoc files so I can fix the above mentioned spacing issues, but looking into insights as to how you got to this stage

[jld01]

@jld01 When you contributed the adoc work you added to help.css. Did you manually craft that css yourself, or was it the result of running asciidoctor one time and then adding it to help.css? I will probably create a separate css for the adoc files so I can fix the above mentioned spacing issues, but looking into insights as to how you got to this stage

@jonahgraham, I copied a minimal set of definitions from the default asciidoctor CSS into help.css as necessary. This was mainly for correct presentation of tables. My goal at that time was to ensure that the asciidoctor-generated pages had a similar look to the existing documentation.

[jld01]

• Check-in generated htm files

If I have understood correctly, the HTML files are generated as part of the PR checks so a contributor need not install Maven themselves.

I can see the benefit for PR review purposes, but, to me, placing generated files under version control seems strange. Perhaps I will warm to the idea. If we do this, then we should make it very clear that contributors are not expected to update the HTML themselves. Perhaps a README.md in each folder containing generated files explaining how and when the content is generated?

[jld01]

Overall, the generated HTML looks great, @jonahgraham. 👍

[jonahgraham]

but, to me, placing generated files under version control seems strange

To me too - can we discuss more quickly at the meeting today if you are coming. I've added it to the agenda.

[jonahgraham]

@jld01 When you contributed the adoc work you added to help.css. Did you manually craft that css yourself, or was it the result of running asciidoctor one time and then adding it to help.css? I will probably create a separate css for the adoc files so I can fix the above mentioned spacing issues, but looking into insights as to how you got to this stage

@jonahgraham, I copied a minimal set of definitions from the default asciidoctor CSS into help.css as necessary. This was mainly for correct presentation of tables. My goal at that time was to ensure that the asciidoctor-generated pages had a similar look to the existing documentation.

I added a new helpadoc.css that is used only by asciidoc files, leaving the original help.css back to its original state. That gives me a place add the missing vertical spacing without breaking the existing html help like this https://github.com/jonahgraham/cdt/blob/2fed9cfc6032a50e4fbe9cc74d998bf7118762b4/doc/org.eclipse.cdt.doc.user/helpadoc.css#L6-L9

[jonahgraham]

Actions from the call (#967) today that affect this:

• Don't commit generated HTML
• Look if pipelined generated html can be saved for easier review
• inline or remove fontawsome so help works in offline mode (or in cases where proxy gets in the way)

[jonahgraham]

In the latest commit I publish docs (conditionally if I set it up right):

Now all that is left is to add a PR comment with the link.

[jonahgraham]

• New profile "asciidoc-auto-refresh" which will auto build the files as edited.

@jld01 - I wanted to bring this to your attention. I added it in the latest commit and found that it is really helpful because it means regeneration is almost instant. See the updated docs readme for more details.