source2adoc

The source2adoc project aims to streamline the process of generating AsciiDoc documentation from inline comments within source code files. With a focus on simplicity and efficiency, this tool converts inline documentation into AsciiDoc files, tailored for seamless integration with Antora, a powerful documentation site generator.

• Documentation Website: https://source2adoc.sommerfeld.io

• Github Repository: https://github.com/sommerfeld-io/source2adoc

• DockerHub: https://hub.docker.com/r/sommerfeldio/source2adoc

• SonarCloud Summary: https://sonarcloud.io/project/overview?id=sommerfeld-io_source2adoc

• Where to file issues: https://github.com/sommerfeld-io/source2adoc/issues

• Project Board for Issues and PRs: https://github.com/orgs/sommerfeld-io/projects/1/views/13

Note	This project is currently in its early stages and is still in the incubation phase. As a result, there are many moving parts and tasks that need to be completed. The project is currently incomplete and work is ongoing to further develop and enhance its functionality.

The primary objective of source2adoc is to facilitate the creation of comprehensive and well-structured documentation directly from code comments. By leveraging the familiar syntax of inline comments in a style similar to JavaDoc, developers can annotate their code, ensuring that insights and explanations are captured and preserved in the generated AsciiDoc files.

The app supports multiple source code languages. The common ground is, that these languages mark their comments through the hash-symbol (#).

• Bash Scripts (*.sh)

• .yaml and .yml

• Vagrantfile

• Dockerfile* (allowing Dockerfile and suffixes like Dockerfile.dev)

• Makefile

source2adoc does not aim at replacing or duplicating existing solutions like JavaDoc or GoDoc! We focus on languages that are not covered by existing solutions in a way we expect!

Requirements and Features

The following section outlines the basic requirements and features of the source2adoc project. These requirements serve as a guideline for the development of the application and provide a clear overview of the expected functionality.

• Initial Documentation Scope

  • Initially, the application will only consider code comments acting as header documentation for entire files.

  • Documentation blocks for classes and functions may be considered in future iterations.

• File Path Preservation

  • When generating documentation, the file path should be preserved. For instance, the source code file src/main/Dockerfile should result in the AsciiDoc file <output-dir>/src/main/dockerfile.adoc. All generated AsciiDoc filenames are lowercase, dots are replaced by dashes.

• File Metadata

  • The caption of the documentation file should automatically be set from the source code file’s name.

  • Additionally, the path of the source code file should be included in the generated docs file file.

  • The actual text of the header docs should be rendered into the file as well. This text will not be translated any further (except for JavDoc-style metadata, see below), it is taken as is, thus allowing to write AsciiDoc markup directly into the source code docs.

• Comment Style

  • The code comments should start with a double hash-symbol (##) as the marker for relevant lines.

  • That means the comment is different from "regular" comments and still allows to use metadata similar to JavaDoc (e.g. @author, @since, …​ but not all of them - see https://en.wikipedia.org/wiki/JavaDoc).

  • @see should generate an xref, @link should generate a static link.

Note	Translating JavaDoc-style metadata is not yet supported, but planned for a future release.

For a detailed overview of the requirements and features of the source2adoc project, refer to the executable specification used for our automated acceptance tests.

Usage

For detailed information on how to use the source2adoc application, take a look at the application’s help output.

docker run sommerfeldio/source2adoc:latest --help

To generate documentation based on the inline comments in a source code file, execute the following command. The --source-dir and --output-dir flags are relative to --workdir (i.e. inside --workdir).

docker run --volume "$(pwd):$(pwd)" --workdir "$(pwd)" \
    sommerfeldio/source2adoc:latest \
        --source-dir src --output-dir docs

To exclude specific files or folders from the documentation generation process, use the --exclude flag. This flag allows you to specify files and folders that should be ignored during the documentation generation process. The --exclude flag is relative to --source-dir (i.e. files to exclude are expected inside --source-dir). Using wildcards as part of the path or filename is not supported (supporting this is planned for a future release).

docker run --volume "$(pwd):$(pwd)" --workdir "$(pwd)" \
    sommerfeldio/source2adoc:latest \
        --source-dir src --output-dir docs \
        --exclude path/inside/src/dir --exclude path/inside/src/dir/script.sh

To generate documentation into an Antora module, execute the following commands.

mkdir -p docs/modules/source2adoc/pages

docker run --volume "$(pwd):$(pwd)" --workdir "$(pwd)" \
    sommerfeldio/source2adoc:latest \
        --source-dir src --output-dir docs/modules/source2adoc/pages

docker run --volume "$(pwd):$(pwd)" --workdir "$(pwd)" \
    sommerfeldio/source2adoc:latest antora \
        --module docs/modules/source2adoc \

echo "  - modules/source2adoc/nav.adoc" >> docs/antora.yml

Important

source2adoc is distributed as a Docker image only, so remember to always use a complete Docker command to run the application, even if --help does not explicitly mentions it.

How to write inline documentation

To generate documentation using source2adoc, it is important to follow a specific syntax for relevant comments. In this syntax, all comments that are considered part of the documentation should be marked with ## at the beginning of each line. These comments will be parsed and included in the generated documentation.

• Rules for the header documentation

  • Files can start with any content they like (allowing e.g. to start bash scripts with a shebang line or yaml files with ---).

  • As soon as a line is found that does start with , all following lines that start with are considered to be part of the header documentation.

  • All lines that do not start with ## are omitted.

  • As soon as an empty line is found, the header documentation is considered to be finished and the parsing stops.

The test data for the source2adoc project (which is used for our unit tests and acceptance tests) provides good examples of how to write inline documentation. See https://github.com/sommerfeld-io/source2adoc/tree/main/testdata/common/good for complete examples for all supported languages.

Risks and Technical Debts

All issues labeled as risk (= some sort of risk or a technical debt) or security (= related to security issues) are tracked as GitHub issue and carry the respective label.

Contact

Feel free to contact me via sebastian@sommerfeld.io.