mulesoft/mule-devkit — Issue #91: [Enhancement] Automatically include markdown pages in generated docs
Author: flbulgarelli
Created: 2012-01-31 15:23:21+00:00
State: open

Currently, in order in include a custom markdown file as a tab in the generated docs, you must explicitly add it in the `maven-javadoc-plugin` configuration. For example:

```xml

org.apache.maven.plugins
maven-javadoc-plugin
2.8

attach-javadocs

jar

org.mule.tools.devkit
mule-devkit-doclet
${mule.devkit.version}

org.mule.devkit.doclet.Doclava
${sun.boot.class.path}

-hdf project.artifactId "${project.artifactId}"
-hdf project.groupId "${project.groupId}"
-hdf project.version "${project.version}"
-hdf project.name "${project.name}"
-hdf project.repo.name "${project.distributionManagement.repository.name}"
-hdf project.repo.id "${project.distributionManagement.repository.id}"
-hdf project.repo.url "${project.distributionManagement.repository.url}"
-hdf project.snapshotRepo.name "${project.distributionManagement.snapshotRepository.name}"
-hdf project.snapshotRepo.id "${project.distributionManagement.snapshotRepository.id}"
-hdf project.snapshotRepo.url "${project.distributionManagement.snapshotRepository.url}"
-d ${project.build.directory}/apidocs
-markdown sqs ${basedir}/SIMPLE-QUEUE-SERVICE.md "SQS Guide"

false
-J-Xmx1024m

```

In this snippet, the line `-markdown sqs ${basedir}/SIMPLE-QUEUE-SERVICE.md "SQS Guide" ` was added in order to instruct the doclet to include file SIMPLE-QUEUE-SERVICE.md in the tab "SQS Guide".

This is error prone, as developers may forget to add the line. It also pollutes the pom with the plugin and its config and introduces logic repetition: the config is the same for all connectors. This is particularly true when you developers use the [devkit-parent](https://github.com/mulesoft/mule-devkit-parent): they do not need to - and should not - add the plugin config, which is inherited.

This could be resolved by adding the following logic to the doc generator: include all markdown files under, say, the doc directory. The tab name would be inferred based on the filename, or - more complex but also more robust -, the first header, as for e.g. Wikhub wiki does.

That way, a consistent directory hierarchy may be ensured through connectors, too.