Child pages
  • Doc Tools Development
Skip to end of metadata
Go to start of metadata

ForgeRock documentation tools include the following projects:

  • forgerock-doc-maven-plugin – a wrapper around other tools, mainly docbkx-tools, but also others such as JCite and PlantUML, this Maven plugin generates output such as HTML & PDF from DocBook 5 XML (and Asciidoc, too) during the site phase of a build.
  • forgerock-doc-maven-plugin-test– a fake doc set that can be used to test forgerock-doc-maven-plugin when you do not want to build real project docs.
  • forgerock-doc-common-content– common content in the form of DocBook 5 XML files, the forgerock-doc-maven-plugin overwrites project files with files from this Maven artifact, with the intent being to have the same content for some things (legal notices, preface, etc.) across all ForgeRock documentation.
  • forgerock-doc-default-branding– in theory this Maven artifact exists to separate the default presentation (look & feel) used during the build from the build mechanism applied by the forgerock-doc-maven-plugin. In practice the separation might leave something to be desired. Ultimately we do want look & feel to be separate and customizable.
  • docs.forgerock.org– the repository of released ForgeRock documentation sets. Send a pull request if you want to update released documentation.

Documentation tools issues are tracked in the DOCS Jira project, and commit notifications go to the docs at forgerock dot org mailing list, for which there's a forum hosted at Nabble.com.

TODO

  • All the doc tools could use some healthy refactoring.
  • They could also use unit testing.
  • The repository of released documentation should probably be hosted at ForgeRock rather than GitHub.com. (Released docs are now on BackStage.)
  • A developer guide (aimed at people improving the doc tools) would be nice. Initial notes: http://commons.forgerock.org/forgerock-doc-maven-plugin/Design.html
  • No labels