SmartThingsCommunity/smartapp-sdk-java

Generate API documentation

rossiam opened this issue · 2 comments

rossiam commented

Set up CI to generate API documentation using JavaDoc. This should result in an artifact published to Maven Central and API docs hosted somewhere. The hosted documentation should be linked in the README.

If necessary, clean up the JavaDoc comments as well so the generated documentation is reasonable.

erodewald commented

Consider using GitBook as part of these docs. I was going to leverage it for the node sdk and other adjacent repos. It automatically syncs markdown in your GitHub to a page at GitBook. I think I can get us an account for unlimited repos with just a few service users since it'll just sync from GitHub, instead of requiring users to log into GitBook and write pages there.

The flow being:

  1. Write JavaDocs in code
  2. Build process generates markdown from JavaDocs
  3. GitBook syncs markdown docs as pages with a nice front-end and dedicated url
rossiam commented

I've spent some time looking into this.

  1. The artifact is already published to Maven.
  2. So far, I have been unable to find a way to publish Javadoc as Markdown for GitBook to consume.

I would recommend just publishing the generated HTML somewhere.