I have my custom rule, let's say with AEM-1 key. So, as it is done here, I make my AEM-1.html resource file with some simple html content and it does not get's picked up by SonarQube 5.1. It refuses to start, because no description is provided for the rule.
I tried different packages names, tried to look for convention in source code etc. What's missing? Is there any documentation on that?
The naming convention is org/sonar/l10n/{plugin key}_{language}/rules/{repository key}/{rule key}.html.
It was documented in http://docs.sonarqube.org/display/DEV/Internationalization at the time rule descriptions supported localization. That's not the case anymore since version 4.2, but these HTML bundles are still supported.
The correct way since version 4.3 is to use the low-level API org.sonar.api.server.rule.RulesDefinition. It allows you to implement any kind over layer over it (xml, json, annotations, ...).