= 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 (#
).
*.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.
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.##
) 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 link:https://github.com/sommerfeld-io/source2adoc/issues/118[planned for a future release].
For a detailed overview of the requirements and features of the source2adoc
project, refer to the link:https://github.com/sommerfeld-io/source2adoc/tree/main/components/test-acceptance/specs[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.
[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
(i.e. inside --workdir
).
[source, bash]
....
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 (link:https://github.com/sommerfeld-io/source2adoc/issues/109[supporting this is planned for a future release]).
[source, bash]
....
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. [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.
---
).
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 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. | // | | // +---------------------------------------------------+