[jira] [Commented] (PDFBOX-2340) Overhaul PDFBox Documentation

["Maruan Sahyoun (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/PDFBOX-2340?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14129243#comment-14129243 ] 

Maruan Sahyoun commented on PDFBOX-2340:
----------------------------------------

Using the Apache CMS parts of the Cookbook could be generated automatically from the examples package. The requirement would be to

- structure the examples package so it reflects the main topics of the Cookbook i.e. create a subdirectory for every topic
- for every topic include an introductory documentation
- put each example for a topic into a subdirectory to the topic directory
- for every example include an introductory documentation
- the documentation can link to lines in the source code. These lines will be pulled into the final document
- if an example does not contain a documentation file it wouldn’t appear in the Cookbook

The other option is to keep the files in the cms package and link from there into the examples.

As an example the OpenEJB examples documentation is done similar to the first option.
Apache Thrift is taking the second approach.


> Overhaul PDFBox Documentation
> -----------------------------
>
>                 Key: PDFBOX-2340
>                 URL: https://issues.apache.org/jira/browse/PDFBOX-2340
>             Project: PDFBox
>          Issue Type: Improvement
>          Components: Documentation
>            Reporter: Maruan Sahyoun
>         Attachments: Mockup_Documentation.png
>
>
> In oder to make it easier for users of PDFBox to work with the library there shall be an enhanced documentation consisting of an introduction, API references and more well documented examples and code snippets (Cookbook).
> In order to make it easier to contribute the Cookbook shall be build automatically from the examples/snippet ‚repository‘.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)