Take all examples in README from source code

ethlo · Feb 8, 2024 · f79e1f3 · f79e1f3
1 parent e98e238
commit f79e1f3
Show file tree

Hide file tree

Showing 4 changed files with 63 additions and 58 deletions.
diff --git a/README.md b/README.md
@@ -33,7 +33,7 @@ Add dependency
 <dependency>
   <groupId>com.ethlo.time</groupId>
   <artifactId>itu</artifactId>
-  <version>1.10.0</version>
+  <version>1.10.1-SNAPSHOT</version>
   <!-- If you want to use minified JAR -->  
   <classifier>small</classifier>
 </dependency>
@@ -49,23 +49,19 @@ This is a collection of usage examples for parsing.
 
 
 
-#### parseRfc3339
-The simplest and fastest way to parse an RFC-3339 (ISO-8601 profile) timestamp by far!
-
-[&raquo; full source](src/test/java/samples/parsing/ITUParserSamples.java#L63C5-L69C5)
+#### parseRfc3339 [&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L63C5-L69C5)
 
+The simplest and fastest way to parse an RFC-3339 (ISO-8601 profile) timestamp by far!
 ```java
 final String text = "2012-12-27T19:07:22.123456789-03:00";
 final OffsetDateTime dateTime = ITU.parseDateTime(text);
 assertThat(dateTime.toString()).isEqualTo(text);
 ```
 
 
-#### parseLenient
-Parses a date-time with flexible granularity. Works for anything from a year to a timestamp with nanoseconds, wih or without timezone offset!
-
-[&raquo; full source](src/test/java/samples/parsing/ITUParserSamples.java#L74C5-L83C5)
+#### parseLenient [&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L74C5-L83C5)
 
+Parses a date-time with flexible granularity. Works for anything from a year to a timestamp with nanoseconds, wih or without timezone offset!
 ```java
 final String text = "2012-12-27T19:07:23.123";
 final DateTime dateTime = ITU.parseLenient(text);
@@ -75,24 +71,20 @@ assertThat(formatted).isEqualTo(text);
 ```
 
 
-#### parseLenientWithCustomSeparators
+#### parseLenientWithCustomSeparators [&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L89C5-L97C5)
+
 In case you encounter the need for a somewhat different time-separator or fraction separator
     you can use the `ParseConfig` to set up you preferred delimiters.
-
-[&raquo; full source](src/test/java/samples/parsing/ITUParserSamples.java#L89C5-L97C5)
-
 ```java
 final ParseConfig config = ParseConfig.DEFAULT.withDateTimeSeparators('T', '|').withFractionSeparators('.', ',');
 final DateTime result = ITU.parseLenient("1999-11-22|11:22:17,191", config);
 assertThat(result.toString()).isEqualTo("1999-11-22T11:22:17.191");
 ```
 
 
-#### parsePosition
-This allows you to track where to start reading. Note that the check for trailing junk is disabled when using ParsePosition.
-
-[&raquo; full source](src/test/java/samples/parsing/ITUParserSamples.java#L102C5-L109C5)
+#### parsePosition [&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L102C5-L109C5)
 
+This allows you to track where to start reading. Note that the check for trailing junk is disabled when using ParsePosition.
 ```java
 final ParsePosition pos = new ParsePosition(10);
 final OffsetDateTime result = ITU.parseDateTime("some-data,1999-11-22T11:22:19+05:30,some-other-data", pos);
@@ -101,11 +93,9 @@ assertThat(pos.getIndex()).isEqualTo(35);
 ```
 
 
-#### explicitGranularity
-This is useful if you need to handle different granularity with different logic or interpolation.
-
-[&raquo; full source](src/test/java/samples/parsing/ITUParserSamples.java#L114C5-L134C5)
+#### explicitGranularity [&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L114C5-L134C5)
 
+This is useful if you need to handle different granularity with different logic or interpolation.
 ```java
 final TemporalHandler<OffsetDateTime> handler = new TemporalHandler<OffsetDateTime>() {
 
@@ -124,24 +114,19 @@ assertThat(result.toString()).isEqualTo("2017-12-06T00:00Z");
 ```
 
 
-#### lenientTimestamp
-In some real world scenarios, it is useful to parse a best-effort timestamp. To ease usage, we can easily convert a raw `DateTime` instance into `Instant`.
+#### lenientTimestamp [&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L140C5-L145C5)
 
+In some real world scenarios, it is useful to parse a best-effort timestamp. To ease usage, we can easily convert a raw `DateTime` instance into `Instant`.
     Note the limitations and the assumption of UTC time-zone, as mentioned in the javadoc.
-
-[&raquo; full source](src/test/java/samples/parsing/ITUParserSamples.java#L141C5-L146C5)
-
 ```java
 final Instant instant = ITU.parseLenient("2017-12-06").toInstant();
 assertThat(instant.toString()).isEqualTo("2017-12-06T00:00:00Z");
 ```
 
 
-#### parseCustomFormat
-In case the format is not supported directly, you can build your own parser.
-
-[&raquo; full source](src/test/java/samples/parsing/ITUParserSamples.java#L151C5-L170C5)
+#### parseCustomFormat [&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L150C5-L169C5)
 
+In case the format is not supported directly, you can build your own parser.
 ```java
 final DateTimeParser parser = DateTimeParsers.of(digits(DAY, 2), separators('-'), digits(MONTH, 2), separators('-'), digits(YEAR, 4), separators(' '), digits(HOUR, 2), digits(MINUTE, 2), digits(SECOND, 2), separators(','), fractions());
 final String text = "31-12-2000 235937,123456";
@@ -150,11 +135,9 @@ assertThat(result.toString()).isEqualTo("2000-12-31T23:59:37.123456");
 ```
 
 
-#### parseUsingInterfaceRfc33939
-`DateTimerParser` interface for RFC-3339
-
-[&raquo; full source](src/test/java/samples/parsing/ITUParserSamples.java#L175C5-L182C5)
+#### parseUsingInterfaceRfc33939 [&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L174C5-L181C5)
 
+`DateTimerParser` interface for RFC-3339
 ```java
 final DateTimeParser parser = DateTimeParsers.rfc3339();
 final String text = "2000-12-31 23:59:37.123456";
@@ -163,11 +146,9 @@ assertThat(result.toString()).isEqualTo("2000-12-31T23:59:37.123456");
 ```
 
 
-#### parseUsingInterfaceLocalTime
-`DateTimerParser` interface for local time
-
-[&raquo; full source](src/test/java/samples/parsing/ITUParserSamples.java#L187C5-L194C5)
+#### parseUsingInterfaceLocalTime [&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L186C5-L193C5)
 
+`DateTimerParser` interface for local time
 ```java
 final DateTimeParser parser = DateTimeParsers.localTime();
 final String text = "23:59:37.123456";
@@ -176,11 +157,9 @@ assertThat(result.toString()).isEqualTo(text);
 ```
 
 
-#### parseUsingInterfaceLocalDate
-`DateTimerParser` interface for local date
-
-[&raquo; full source](src/test/java/samples/parsing/ITUParserSamples.java#L199C5-L206C5)
+#### parseUsingInterfaceLocalDate [&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L198C5-L205C5)
 
+`DateTimerParser` interface for local date
 ```java
 final DateTimeParser parser = DateTimeParsers.localDate();
 final String text = "2013-12-24";
@@ -198,11 +177,9 @@ This is a collection of usage examples for formatting.
 
 
 
-#### formatRfc3339WithUTC
-The simplest and fastest way to format an RFC-3339 (ISO-8601 profile) timestamp by far!
-
-[&raquo; full source](src/test/java/samples/formatting/ITUFormattingSamples.java#L44C5-L52C5)
+#### formatRfc3339WithUTC [&raquo; source](src/test/java/samples/formatting/ITUFormattingSamples.java#L44C5-L52C5)
 
+The simplest and fastest way to format an RFC-3339 (ISO-8601 profile) timestamp by far!
 ```java
 final OffsetDateTime input = OffsetDateTime.of(2012, 12, 27, 19, 7, 22, 123456789, ZoneOffset.ofHoursMinutes(-3, 0));
 assertThat(ITU.formatUtcNano(input)).isEqualTo("2012-12-27T22:07:22.123456789Z");
@@ -219,11 +196,9 @@ assertThat(ITU.formatUtc(input)).isEqualTo("2012-12-27T22:07:22Z");
 
 
 
-#### parseLeapSecond
-Parse a valid leap-second (i.e. it is on a date that would allow for it, and it is also in the list of known actual leap-seconds).
-
-[&raquo; full source](src/test/java/samples/leapsecond/ITULeapSecondSamples.java#L43C5-L57C5)
+#### parseLeapSecond [&raquo; source](src/test/java/samples/leapsecond/ITULeapSecondSamples.java#L43C5-L57C5)
 
+Parse a valid leap-second (i.e. it is on a date that would allow for it, and it is also in the list of known actual leap-seconds).
 ```java
 try {
     ITU.parseDateTime("1990-12-31T15:59:60-08:00");

diff --git a/pom.xml b/pom.xml
@@ -23,7 +23,7 @@ limitations under the License.
     <groupId>com.ethlo.time</groupId>
     <packaging>bundle</packaging>
     <artifactId>itu</artifactId>
-    <version>1.10.0</version>
+    <version>1.10.1-SNAPSHOT</version>
     <name>Internet Time Utility</name>
     <description>Extremely fast date-time parser and formatter - RFC 3339 (ISO 8601 profile) and W3C format
     </description>
@@ -171,7 +171,7 @@ limitations under the License.
             <plugin>
                 <groupId>org.codehaus.mojo</groupId>
                 <artifactId>license-maven-plugin</artifactId>
-                <version>2.0.0</version>
+                <version>2.2.0</version>
                 <configuration>
                     <verbose>false</verbose>
                     <addSvnKeyWords>true</addSvnKeyWords>
@@ -186,7 +186,7 @@ limitations under the License.
                         <configuration>
                             <licenseName>apache_v2</licenseName>
                             <inceptionYear>2017</inceptionYear>
-                            <organizationName>Morten Haraldsen (ethlo)</organizationName>
+                            <organizationName>Morten Haraldsen @ethlo</organizationName>
                             <addSvnKeyWords>false</addSvnKeyWords>
                             <canUpdateDescription>false</canUpdateDescription>
                             <roots>
@@ -228,6 +228,19 @@ limitations under the License.
                 <version>3.4.3</version>
             </extension>
         </extensions>
+        <resources>
+            <resource>
+                <directory>src/main/resources</directory>
+            </resource>
+            <resource>
+                <filtering>true</filtering>
+                <directory>${project.basedir}/src/site</directory>
+                <includes>
+                    <include>README.md</include>
+                </includes>
+                <targetPath>${project.basedir}</targetPath>
+            </resource>
+        </resources>
     </build>
     <distributionManagement>
         <repository>
@@ -300,6 +313,27 @@ limitations under the License.
                             </libs>
                         </configuration>
                     </plugin>
+                    <plugin>
+                        <groupId>com.ethlo.maven</groupId>
+                        <artifactId>java-code-extractor-maven-plugin</artifactId>
+                        <version>1.0.0-SNAPSHOT</version>
+                        <configuration>
+                            <template>src/site/sample-code.template.md</template>
+                            <sources>
+                                <source>src/test/java/samples/parsing</source>
+                                <source>src/test/java/samples/formatting</source>
+                                <source>src/test/java/samples/leapsecond</source>
+                            </sources>
+                        </configuration>
+                        <executions>
+                            <execution>
+                                <phase>initialize</phase>
+                                <goals>
+                                    <goal>extract</goal>
+                                </goals>
+                            </execution>
+                        </executions>
+                    </plugin>
                 </plugins>
             </build>
         </profile>

diff --git a/src/site/sample-code.template.md b/src/site/sample-code.template.md
@@ -2,13 +2,10 @@
 
 {% for method in methods %}
 
-#### {{method.name}}
+#### {{method.name}} [&raquo; source]({{class.path}}/{{class.name}}.java#L{{method.range.begin.line}}C{{method.range.begin.column}}-L{{method.range.end.line}}C{{method.range.end.column}})
 
 {{method.description | trim | raw }}
 
-
-[&raquo; full source]({{class.path}}/{{class.name}}.java#L{{method.range.begin.line}}C{{method.range.begin.column}}-L{{method.range.end.line}}C{{method.range.end.column}})
-
 ```java
 {{method.body | trim | raw }}
 

diff --git a/src/test/java/samples/parsing/ITUParserSamples.java b/src/test/java/samples/parsing/ITUParserSamples.java
@@ -135,7 +135,6 @@ public OffsetDateTime handle(final OffsetDateTime offsetDateTime)
 
     /*
     In some real world scenarios, it is useful to parse a best-effort timestamp. To ease usage, we can easily convert a raw `DateTime` instance into `Instant`.
-
     Note the limitations and the assumption of UTC time-zone, as mentioned in the javadoc.
     */
     @Test