Add generation of a PDF of the docs

[qwasson]

(This issue existed in the previous Jira issue tracker as ENUNCIATE-555)

It would be useful to be able to generate a PDF with equivalent documentation to that in the HTML version.

[stoicflame]

Thanks for the request.

[stoicflame]

This enhancement is currently seeking a sponsor. If anybody is willing to sponsor the work, reach out to me and I'd be happy to pick it up.

[learsix]

Hi,

I ran into the same problem and found a simple solution:

• it's quite easy to modify the freemarker template of the docs module to generate an asciidoc file. The structure of this asciidoc file can be inspired by the nice structure of the existing html documentation.
• using this asciidoc file, you can generate a pdf file using the asciidoctor and asciidoctorj-pdf projects. I use maven and it turn out to be quite simple to trigger the asciidoctor plugin after the enunciate plugin.

I'd be happy to share the modified freemarker template if you think this is relevant.

[stoicflame]

@learsix, what if you just created a gist for us?

Sounds cool! Thanks!

[learsix]

You'll find it here: https://gist.github.com/learsix/2ae416c7bfb0b5a62b239071623c835d

This has not been heavely tested:

• This is not directly what I use. I removed some personalization that I did on the whole template.
• I don't use resourceGroups / serviceGroups : I may have missed some things here.

The macro html2asciidoc matches our Javadoc conventions, but it may not be complete.

I just put my additions in the gist to generate the asciidoc file. On my side this is included in the docs module template (doc.fmt). To generate the pdf I then call asciidoctor using the enunciate generated doc dir as a source. I found it nice to be able to download the pdf: I move the generated pdf in the enunciate dir and modified the docs.fmt template to include a link.

Maven configuration example for pdf generation:

<plugin>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-maven-plugin</artifactId>
  <version>1.5.3</version>
  <dependencies>
    <dependency>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctorj-pdf</artifactId>
      <version>1.5.0-alpha.11</version>
    </dependency>
  </dependencies>
  <configuration>
    <!-- the new doc generated by enunciate -->
    <sourceDocumentName>documentation_en.adoc</sourceDocumentName>
    <sourceDirectory>${project.build.directory}/enunciate-publish/docs</sourceDirectory>
    <!-- where the pdf will be put -->
    <outputDirectory>${project.build.directory}/asciidoctor-publish/docs</outputDirectory>
    <backend>pdf</backend>
    <!-- optional - my pdf theme includes a logo, it's here -->
    <imagesDir>${project.basedir}/src/main/asciidoctor/images</imagesDir>
    <attributes>
      <icons>font</icons>
      <pagenums/>
      <toc/>
      <idprefix/>
      <idseparator>-</idseparator>
       <!-- optional - I did some personalization of the default pdf theme -->
      <pdf-stylesdir>${project.basedir}/src/main/asciidoctor</pdf-stylesdir>
      <pdf-style>mystyle</pdf-style>
    </attributes>
  </configuration>
  <execution>
     <phase>generate-resources</phase>
    <goals><goal>process-asciidoc</goal></goals>
  </execution>
</plugin>