= source2adoc Sebastian Sommerfeld sebastian@sommerfeld.io :github-org: sommerfeld-io :project-name: source2adoc :url-project: https://github.com/{github-org}/{project-name} :github-actions-url: {url-project}/actions/workflows :job: pipeline.yml :badge: badge.svg

The link:https://github.com/sommerfeld-io/source2adoc[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 link:https://antora.org[Antora], a powerful documentation site generator.

image:{github-actions-url}/{job}/{badge}[Github Badge, link={github-actions-url}/{job}]

• Documentation Website: https://source2adoc.sommerfeld.io
• Github Repository: {url-project}
• DockerHub: https://hub.docker.com/r/sommerfeldio/{project-name}
• SonarCloud Summary: https://sonarcloud.io/project/overview?id={github-org}_{project-name}
• Where to file issues: {url-project}/issues

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
• yaml and yml
• Vagrantfile
• Dockerfile
• 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.
• 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 comment style should resemble JavaDoc but a double hash-symbol (##) as the marker for commented 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.

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

[source, bash] .... 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):

[source, bash] .... docker run --volume "$(pwd):$(pwd)" --workdir "$(pwd)" sommerfeldio/source2adoc:latest --source-dir ./src --output-dir ./docs ....

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

[source, bash] .... 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.

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

• 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.

== Risks and Technical Debts link:{url-project}/issues?q=is%3Aissue+label%3Asecurity%2Crisk+is%3Aopen[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.

// +---------------------------------------------------+ // | | // | DO NOT EDIT DIRECTLY !!!!! | // | | // | File is auto-generated by pipeline. | // | Contents are based on Antora docs. | // | | // +---------------------------------------------------+