About

PzdcDoc is the complete ready-to-use solution, providing clear way and workflow for organizing software documentation.

Based on AsciidoctorJ, Java binding of the excellent software documentation framework Asciidoctor. Thanks to 100% compatibility to AsciiDoctor, existing documentation files may be re-used.

On top of AsciiDoctor there are added the following features:

  • Delivered as a single Java artifact in Maven repository for simple integration in existing build processes.

  • Building documentation out of many files structured in original way with ToC.

  • Preserving structure, preview of documentation is available in GitLab and GitHub.

  • Internal references checking, no more broken links.

  • Produce embedded JS search over EN, RU and DE using LunrJS and substring.

  • Diagrams generation: Draw.IO, Ditaa, PlantUML formats are supported.

  • Extension for referencing of JavaDoc by class name.

  • Live snippets for extracting samples directly out of source files with simple validation of actuality.

  • CSS enhancements.

References

How to use

Clone the GIT repository, after execute in the directory one of the following tests. You would need Java version 21 or higher. Both produce result to target/doc-out, these files may be published on HTTP server. See tasks configuration in build.gradle file.

Simple case with local files

gradlew

Default task buildDemoDocLocal uses src/doc directory as an input and compiles classes from sources. Good for first start and testing changes.

Complex case with checking out GIT

In most of projects such a complex solution doesn’t make sense. Was created for demo purposes and to re-use shown by default in GitLab/GitHub README.adoc file.

 
gradlew buildDemoDoc

Extracts the project data from GIT and uses Maven artifact of PzdcDoc for running. That sample may be useful for the case of building documentation out of many GIT projects. The result from master branch is published to: http://pzdcdoc.org/demo

History

Initially this tool was developed for the BGERP, project of Open Source ERP/CRM system. It was successfully used there as one system with GIT stored sources for support of:

  • product documentation;

  • samples and articles;

  • database structure

The single tool has replaced Confluence + MediaWiki + self-written DB structure describing utility in a more convenient way. Ideally fits for continuous delivery approach, when documentation is considered as essential part of product and written, stored, handled together with other sources. Documentation is automatically built using GitLab CI and published, you may see the result here.

How does it work

  • As parameter generator takes input and output directories.

  • Input directory may be copied directly from project or checked out from version control to outside like target. First way is easier, in the second one may be combined doc sources out of many GIT projects. In the input directory may be placed:

  • index.adoc with table of contents. Only one index on the highest level will be used.

  • pzdcdoc.xml file with AsciiDoctor attributes, these will be implicitly included in each of .adoc file starting from the directory, where pzdcdoc.xml is placed. This means, that this configuration is inherited and may be overwritten.

  • The generator goes through all the files in input dir and converting all with extension .adoc them to .html.

    • Directory starting from . are skipped.

    • Includes have to be named .adocf to avoid converting.

    • Resources (files, images) are recommended be placed in _res subdirectory near of referencing .adoc file, but you may reference as well any project file, it will be copied to the target directory.

  • All the used references between .adoc are relative and automatically converted to HTML.

GIT workflow

Documentation sources have to be treated as high-level program code, written for humans. For easily managing all of those sources together, recommended to do each change in separated GIT branch, do not merge it on master, but pick all the modification in single commit on master whenever work is done. Use merge squash of similar operations. You may found here detailed description of such workflow.

For doing modifications in documentation only recommended to make one more branch doc-no-merge in each repo, do there intermediate changes and use it for building documentation. Periodically content of this branch is picked to master using merge with squash.

Feedback

The list of currently known issues same as new wishes can be sent here: https://team.bgerp.org/open/process/14247