We are a github organisation. You are invited to participate.
simple doc generator based on unit tests
Stable (Maven Central Repository, Released: 12.02.2023 - wait 24hrs for maven central)
<dependency>
<groupId>de.flapdoodle.testdoc</groupId>
<artifactId>de.flapdoodle.testdoc</artifactId>
<version>1.6.1</version>
</dependency>
Use Recording as RegisterExtension
like this:
public class HowToTest {
@RegisterExtension
public static Recording recording=Recorder.with("howto.md", TabSize.spaces(2))
.sourceCodeOf("fooClass", FooClass.class);
@Test
public void theMethodNameIsTheKey() {
// everything after this marker ...
recording.include(BarClass.class, Includes.WithoutPackage, Includes.Trim, Includes.WithoutImports);
recording.begin();
boolean sampleVar = true;
assertTrue(sampleVar);
recording.end();
// nothing after this marker
}
@Test
public void multipleCodeBlocks() {
recording.begin();
// first block
recording.end();
recording.begin("named");
// second block - named
recording.end();
}
}
.. and create MarkDown template as TestClass-Resource (same package):
# How To
some text
## Simple Sample
```
${theMethodNameIsTheKey}
```
### .. with class include
```
${theMethodNameIsTheKey.BarClass}
```
## Sample with more than one block
```
${multipleCodeBlocks}
```
## Sample with more than one block - alt version
```
${multipleCodeBlocks.1}
```
```
${multipleCodeBlocks.2}
```
```
${multipleCodeBlocks.named}
```
# Includes
```
${fooClass}
```
```
${theMethodNameIsTheKey.BarClass}
```
... add a property in your pom.xml
:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.19.1</version>
<configuration>
<systemPropertyVariables>
<de.flapdoodle.testdoc.destination>${project.build.directory}</de.flapdoodle.testdoc.destination>
</systemPropertyVariables>
</configuration>
</plugin>
... and you will get this:
# How To
some text
## Simple Sample
```
boolean sampleVar = true;
assertTrue(sampleVar);
```
### .. with class include
```
public class BarClass {
Map<String, Object> map;
}
```
## Sample with more than one block
```
// first block
...
// second block - named
```
## Sample with more than one block - alt version
```
// first block
```
```
// second block - named
```
```
// second block - named
```
# Includes
```
/**
* Copyright (C) 2016
* Michael Mosmann <michael@mosmann.de>
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package de.flapdoodle.testdoc;
public class FooClass {
// nothing here
}
```
```
public class BarClass {
Map<String, Object> map;
}
```
With different replacement pattern as in:
public class HowToDifferentReplacementPatternTest {
@RegisterExtension
public static Recording recording=Recorder.with("howtoDoubleCurly.md", ReplacementPattern.DOUBLE_CURLY, TabSize.spaces(2))
.sourceCodeOf("fooClass", FooClass.class);
@Test
public void theMethodNameIsTheKey() {
// everything after this marker ...
recording.include(BarClass.class, Includes.WithoutPackage, Includes.Trim, Includes.WithoutImports);
recording.begin();
boolean sampleVar = true;
assertTrue(sampleVar);
recording.end();
// nothing after this marker
}
@Test
public void multipleCodeBlocks() {
recording.begin();
// first block
recording.end();
recording.begin("named");
// second block - named
recording.end();
}
}
.. and a differnt template as TestClass-Resource (same package):
# How To
some text
## Simple Sample
```
{{theMethodNameIsTheKey}}
```
### .. with class include
```
{{theMethodNameIsTheKey.BarClass}}
```
## Sample with more than one block
```
{{multipleCodeBlocks}}
```
## Sample with more than one block - alt version
```
{{multipleCodeBlocks.1}}
```
```
{{multipleCodeBlocks.2}}
```
```
{{multipleCodeBlocks.named}}
```
# Includes
```
{{fooClass}}
```
```
{{theMethodNameIsTheKey.BarClass}}
```
... and you will get this:
# How To
some text
## Simple Sample
```
boolean sampleVar = true;
assertTrue(sampleVar);
```
### .. with class include
```
public class BarClass {
Map<String, Object> map;
}
```
## Sample with more than one block
```
// first block
...
// second block - named
```
## Sample with more than one block - alt version
```
// first block
```
```
// second block - named
```
```
// second block - named
```
# Includes
```
/**
* Copyright (C) 2016
* Michael Mosmann <michael@mosmann.de>
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package de.flapdoodle.testdoc;
public class FooClass {
// nothing here
}
```
```
public class BarClass {
Map<String, Object> map;
}
```
.. to add a method called inside test class you can
public class MethodSourceTest {
@RegisterExtension
public static Recording recording=Recorder.with("method-source.md", TabSize.spaces(2));
@Test
public void testMethod() {
recording.begin();
otherMethod();
recording.end();
}
public void otherMethod() {
recording.thisMethod("otherMethod");
// you should include this
// and this
}
}
.. and create MarkDown template as TestClass-Resource (same package):
# include method source code
```java
${testMethod}
```
calls:
```java
${otherMethod}
```
... and you will get this:
# include method source code
```java
otherMethod();
```
calls:
```java
public void otherMethod() {
// you should include this
// and this
}
```
... to write some files as part of the test
public class HowToAddFilesTest {
@RegisterExtension
public static Recording recording=Recorder.with("HowToAddFiles.md", TabSize.spaces(2))
.renderTo("howto-add-files.md");
@Test
public void inAndMethod() {
recording.file("file", "test.txt", "could be any content".getBytes(StandardCharsets.UTF_8));
recording.begin();
// ..
recording.end();
}
}
.. and create MarkDown template as TestClass-Resource (same package):
# An other HowTo
this documentation references this [file](${inAndMethod.file})
... and you will get this:
# An other HowTo
this documentation references this [file](test.txt)
with these files generated: test.txt
If you forgot to create the template, then this content will be rendered into the document:
# document from generated template
As you did not create a matching template with the name
> `missingTemplate.md`
in the same package as
> `de.flapdoodle.testdoc.MissingTemplateTest`
the content of this file is generated from the recordings of your test class.
In your test following parts were recorded:
* `firstTest`
* `firstTest.1`
To insert the content of a part into the generated document you must embed a name
from this list between a starting `${` and `}`.