= 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}]
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 (#
).
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.
src/main/Dockerfile
should result in the AsciiDoc file <output-dir>/src/main/Dockerfile.adoc
.##
) 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.
---
).
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. | // | | // +---------------------------------------------------+