https://github.com/ethlo/source-extractor-maven-plugin
Source extractor for documentation purposes. Extract code from actual source code to avoid maintaining codesamples in documentation. Link to full examples.
https://github.com/ethlo/source-extractor-maven-plugin
documentation java source-code technical-writing
Last synced: 11 months ago
JSON representation
Source extractor for documentation purposes. Extract code from actual source code to avoid maintaining codesamples in documentation. Link to full examples.
- Host: GitHub
- URL: https://github.com/ethlo/source-extractor-maven-plugin
- Owner: ethlo
- Created: 2024-02-07T20:20:18.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-11T10:05:50.000Z (over 2 years ago)
- Last Synced: 2025-06-10T23:06:52.505Z (about 1 year ago)
- Topics: documentation, java, source-code, technical-writing
- Language: Java
- Homepage:
- Size: 34.2 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
### source-extractor-maven-plugin
[](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.ethlo.time%22%20a%3A%22itu%22)
[](LICENSE)
An opinionated little tool to extract code samples for inclusion in HTML or markdown to avoid maintaining example code separately from tests.
An example can be seen here: https://github.com/ethlo/itu/?tab=readme-ov-file#parsing
Standing on the shoulders of these awesome projects:
* https://github.com/javaparser/javaparser
* https://github.com/PebbleTemplates/pebble
### How it works
You define the plugin to extract methods from classes in a given package. These are processed and then rendered with the specified template, and are available as a variable name matching the defined `` name.
This variable can then be used in maven resource interpolation to be included in a readme file, for example.
### Usage
We need to set up the plugin to extract the relevant source code. I recommend a package with samples you want to showcase, like `src/test/java/mysamples`.
The example below stores a `README.md` _template_ in `src/site`.
The `pom.xml` resources section (must be filtered) so that you can include snippets rendered.
```xml
com.ethlo.documentation
source-extractor-maven-plugin
0.3.0
src/main/site/github.template.md
src/test/java/samples
initialize
extract
src/main/resources
true
${project.basedir}/src/main/site
README.md
${project.basedir}
```
### Extracted samples
#### showOffFeatureA [» source](src/test/java/samples/SampleCode.java#L28C5-L37C6)
Description of the cool feature A goes here!
```java
final List list = Arrays.asList("something", "cool");
assert list.size() == 2;
assert list != null;
```
#### showOffFeatureB [» source](src/test/java/samples/SampleCode.java#L39C5-L50C6)
Description of the cool feature B goes here!
And some more here!
```java
final List list = Arrays.asList("something", "else", "cool");
assert list.size() == 2;
assert list != null;
```