[docs] Minor bug fixes in the documentation generator.

Signed-off-by: Stéphane Galland <galland@arakhne.org>

main/externalmaven/io.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/markdown/MarkdownParser.java

@@ -53,6 +53,7 @@
 import org.eclipse.core.runtime.Assert;
 import org.eclipse.xtext.util.Strings;
 import org.eclipse.xtext.xbase.compiler.output.ITreeAppendable;
+import org.eclipse.xtext.xbase.lib.Functions.Function2;
 import org.eclipse.xtext.xbase.lib.IntegerRange;
 
 import io.sarl.maven.docs.parser.AbstractMarkerLanguageParser;
@@ -145,17 +146,13 @@ public void setGithubExtensionEnable(boolean enable) {
 	}
 
 	private void updateBlockFormatter() {
+		final Function2<String, String, String> formatter;
 		if (isGithubExtensionEnable()) {
-			getDocumentParser().setBlockCodeTemplate((languageName, content) -> {
-				return "```" + Strings.emptyIfNull(languageName).toLowerCase() + "\n" //$NON-NLS-1$ //$NON-NLS-2$
-						+ Pattern.compile("^", Pattern.MULTILINE).matcher(content).replaceAll("\t") //$NON-NLS-1$ //$NON-NLS-2$
-						+ "```\n"; //$NON-NLS-1$
-			});
+			formatter = SarlDocumentationParser.getFencedCodeBlockFormatter();
 		} else {
-			getDocumentParser().setBlockCodeTemplate((languageName, content) -> {
-				return Pattern.compile("^", Pattern.MULTILINE).matcher(content).replaceAll("\t"); //$NON-NLS-1$ //$NON-NLS-2$
-			});
+			formatter = SarlDocumentationParser.getBasicCodeBlockFormatter();
 		}
+		getDocumentParser().setBlockCodeTemplate(formatter);
 	}
 
 	@Override
@@ -537,9 +534,7 @@ protected String updateOutline(String content) {
 					sectionNumber = formatSectionNumber(sections);
 
 					if (Strings.isEmpty(sectionId)) {
-						sectionId = computeHeaderId(
-								isAutoSectionNumbering() ? sectionNumber : null,
-								title);
+						sectionId = computeHeaderId(sectionNumber, title);
 						if (!identifiers.add(sectionId)) {
 							int idNum = 1;
 							String nbId = sectionId + "-" + idNum; //$NON-NLS-1$
@@ -569,6 +564,19 @@ protected String updateOutline(String content) {
 
 					addOutlineEntry(outline, relLevel + 1, sectionNumber, title, sectionId, styledOutline);
 				} else {
+					if (Strings.isEmpty(sectionId)) {
+						sectionId = computeHeaderId(null, title);
+						if (!identifiers.add(sectionId)) {
+							int idNum = 1;
+							String nbId = sectionId + "-" + idNum; //$NON-NLS-1$
+							while (!identifiers.add(nbId)) {
+								++idNum;
+								nbId = sectionId + "-" + idNum; //$NON-NLS-1$
+							}
+							sectionId = nbId;
+						}
+					}
+
 					addOutlineEntry(outline, relLevel + 1, null, title, sectionId, styledOutline);
 				}
 				prevLevel = relLevel;

main/externalmaven/io.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/parser/SarlDocumentationParser.java

@@ -143,6 +143,30 @@ public void setOutputLanguage(@Named(Constants.LANGUAGE_NAME) String outputLangu
 		this.languageName = null;
 	}
 
+	/** Replies the fenced code block formatter.
+	 *
+	 * <p>This code block formatter is usually used by Github.
+	 *
+	 * @return the formatter.
+	 */
+	public static Function2<String, String, String> getFencedCodeBlockFormatter() {
+		return (languageName, content) -> {
+			return "```" + Strings.nullToEmpty(languageName).toLowerCase() + "\n" //$NON-NLS-1$ //$NON-NLS-2$
+					+ Pattern.compile("^", Pattern.MULTILINE).matcher(content).replaceAll("\t") //$NON-NLS-1$ //$NON-NLS-2$
+					+ "```\n"; //$NON-NLS-1$
+		};
+	}
+
+	/** Replies the basic code block formatter.
+	 *
+	 * @return the formatter.
+	 */
+	public static Function2<String, String, String> getBasicCodeBlockFormatter() {
+		return (languageName, content) -> {
+			return Pattern.compile("^", Pattern.MULTILINE).matcher(content).replaceAll("\t"); //$NON-NLS-1$ //$NON-NLS-2$
+		};
+	}
+
 	/** Replies the name of the language.
 	 *
 	 * @return the language name, or {@code null} for ignoring the language name.
@@ -412,6 +436,9 @@ public String getInlineCodeTemplate() {
 	}
 
 	/** Set the template for block codes.
+	 *
+	 * <p>The first parameter of the function is the language name. The second parameter is
+	 * the code to format.
 	 *
 	 * @param template the template.
 	 */
@@ -420,6 +447,9 @@ public void setBlockCodeTemplate(Function2<String, String, String> template) {
 	}
 
 	/** Replies the template for block codes.
+	 *
+	 * <p>The first parameter of the function is the language name. The second parameter is
+	 * the code to format.
 	 *
 	 * @return the template.
 	 */
@@ -938,7 +968,7 @@ protected static String formatBlockText(String content, String languageName, Fun
 			buffer.append("\n"); //$NON-NLS-1$
 		}
 		replacement = buffer.toString().replaceFirst("[\n\r]+$", "\n"); //$NON-NLS-1$ //$NON-NLS-2$
-		if (!Strings.isNullOrEmpty(replacement)) {
+		if (!Strings.isNullOrEmpty(replacement) && !"\n".equals(replacement)) { //$NON-NLS-1$
 			if (blockFormat != null) {
 				return blockFormat.apply(languageName, replacement);
 			}

tests/io.sarl.maven.docs.generator.tests/src/test/java/io/sarl/maven/docs/generator/tests/markdown/MarkdownParserTest.java

@@ -51,7 +51,6 @@
 @RunWith(Suite.class)
 @SuiteClasses({
 	MarkdownParserTest.TransformTest.class,
-	MarkdownParserTest.ValidationTest.class,
 })
 @SuppressWarnings("all")
 public class MarkdownParserTest {
@@ -72,6 +71,7 @@ public static class TransformTest {
 		public void setUp() {
 			Injector injector = SARLStandaloneSetup.doSetup();
 			this.parser = injector.getInstance(MarkdownParser.class);
+			this.parser.setOutlineStyleId(null);
 		}
 
 		@Test
@@ -81,10 +81,16 @@ public void outline01_level1() throws Exception {
 			this.parser.setAutoSectionNumbering(true);
 			String value = this.parser.transform(file);
 			assertEquals("#1. Title\n\n##1.1. Title 0\n\nthis is a fake text done for testing. this is a fake text done "
-					+ "for testing. this is a fake text done for testing.\n\n\n* [1. Title](#title)\n"
-					+ "  * [1.1. Title 0](#title-0)\n* [2. Title 1](#title-1)\n  * [2.1. Title 2](#title-2)\n"
-					+ "    * [2.1.1. Title 3](#title-3)\n  * [2.2. Title 4](#title-4)\n  * [2.3. Title 5](#title-5)\n"
-					+ "* [3. Title 6](#title-6)\n\n\n\nthis is a fake text done for testing.\n\n#2. Title 1\n\n"
+					+ "for testing. this is a fake text done for testing.\n\n\n"
+					+ "> * [1. Title](#1-title)\n"
+					+ "> \t* [1.1. Title 0](#1-1-title-0)\n"
+					+ "> * [2. Title 1](#2-title-1)\n"
+					+ "> \t* [2.1. Title 2](#2-1-title-2)\n"
+					+ "> \t\t* [2.1.1. Title 3](#2-1-1-title-3)\n"
+					+ "> \t* [2.2. Title 4](#2-2-title-4)\n"
+					+ "> \t* [2.3. Title 5](#2-3-title-5)\n"
+					+ "> * [3. Title 6](#3-title-6)\n"
+					+ "\n\n\nthis is a fake text done for testing.\n\n#2. Title 1\n\n"
 					+ "this is a fake text done for testing. this is a fake text done for testing. this is a\n"
 					+ "\n##2.1. Title 2\n\nfake text done for testing. this is a fake text\n\n###2.1.1. Title 3\n\n"
 					+ "##2.2. Title 4\n\n##2.3. Title 5\n\ndone for testing. this is a fake text done\nfor testing. "
@@ -101,11 +107,13 @@ public void outline01_level2() throws Exception {
 			this.parser.setAutoSectionNumbering(true);
 			String value = this.parser.transform(file);
 			assertEquals("# Title\n\n##1. Title 0\n\nthis is a fake text done for testing. this is a fake text done "
-					+ "for testing. this is a fake text done for testing.\n\n\n* [1. Title 0](#title-0)\n"
-					+ "* [2. Title 2](#title-2)\n"
-					+ "  * [2.1. Title 3](#title-3)\n"
-					+ "* [3. Title 4](#title-4)\n"
-					+ "* [4. Title 5](#title-5)\n\n\n\nthis is a fake text done for testing.\n\n# Title 1\n\n"
+					+ "for testing. this is a fake text done for testing.\n\n\n"
+					+ "> * [1. Title 0](#1-title-0)\n"
+					+ "> * [2. Title 2](#2-title-2)\n"
+					+ "> \t* [2.1. Title 3](#2-1-title-3)\n"
+					+ "> * [3. Title 4](#3-title-4)\n"
+					+ "> * [4. Title 5](#4-title-5)\n"
+					+ "\n\n\nthis is a fake text done for testing.\n\n# Title 1\n\n"
 					+ "this is a fake text done for testing. this is a fake text done for testing. this is a\n"
 					+ "\n##2. Title 2\n\nfake text done for testing. this is a fake text\n\n###2.1. Title 3\n\n"
 					+ "##3. Title 4\n\n##4. Title 5\n\ndone for testing. this is a fake text done\nfor testing. "
@@ -122,7 +130,8 @@ public void outline01_level3() throws Exception {
 			this.parser.setAutoSectionNumbering(true);
 			String value = this.parser.transform(file);
 			assertEquals("# Title\n\n## Title 0\n\nthis is a fake text done for testing. this is a fake text done "
-					+ "for testing. this is a fake text done for testing.\n\n\n* [1. Title 3](#title-3)\n"
+					+ "for testing. this is a fake text done for testing.\n\n\n"
+					+ "> * [1. Title 3](#1-title-3)\n"
 					+ "\n\n\nthis is a fake text done for testing.\n\n# Title 1\n\n"
 					+ "this is a fake text done for testing. this is a fake text done for testing. this is a\n"
 					+ "\n## Title 2\n\nfake text done for testing. this is a fake text\n\n###1. Title 3\n\n"
@@ -140,10 +149,16 @@ public void outline02_level1() throws Exception {
 			this.parser.setAutoSectionNumbering(false);
 			String value = this.parser.transform(file);
 			assertEquals("# Title\n\n## Title 0\n\nthis is a fake text done for testing. this is a fake text "
-					+ "done for testing. this is a fake text done for testing.\n\n\n* [Title](#title)\n  "
-					+ "* [Title 0](#title-0)\n* [Title 1](#title-1)\n  * [Title 2](#title-2)\n    "
-					+ "* [Title 3](#title-3)\n  * [Title 4](#title-4)\n  * [Title 5](#title-5)\n* "
-					+ "[Title 6](#title-6)\n\n\n\nthis is a fake text done for testing.\n\n# Title 1\n\nthis is a fake "
+					+ "done for testing. this is a fake text done for testing.\n\n\n"
+					+ "> * [Title](#title)\n"
+					+ "> \t* [Title 0](#title-0)\n"
+					+ "> * [Title 1](#title-1)\n"
+					+ "> \t* [Title 2](#title-2)\n"
+					+ "> \t\t* [Title 3](#title-3)\n"
+					+ "> \t* [Title 4](#title-4)\n"
+					+ "> \t* [Title 5](#title-5)\n"
+					+ "> * [Title 6](#title-6)\n"
+					+ "\n\n\nthis is a fake text done for testing.\n\n# Title 1\n\nthis is a fake "
 					+ "text done for testing. this is a fake text done for testing. this is a\n\n## Title 2\n"
 					+ "\nfake text done for testing. this is a fake text\n\n### Title 3\n\n## Title 4\n"
 					+ "\n## Title 5\n\ndone for testing. this is a fake text done\nfor testing. this is a "
@@ -160,8 +175,12 @@ public void outline02_level2() throws Exception {
 			this.parser.setAutoSectionNumbering(false);
 			String value = this.parser.transform(file);
 			assertEquals("# Title\n\n## Title 0\n\nthis is a fake text done for testing. this is a fake text "
-					+ "done for testing. this is a fake text done for testing.\n\n\n* [Title 0](#title-0)\n"
-					+ "* [Title 2](#title-2)\n  * [Title 3](#title-3)\n* [Title 4](#title-4)\n* [Title 5](#title-5)\n"
+					+ "done for testing. this is a fake text done for testing.\n\n\n"
+					+ "> * [Title 0](#title-0)\n"
+					+ "> * [Title 2](#title-2)\n"
+					+ "> \t* [Title 3](#title-3)\n"
+					+ "> * [Title 4](#title-4)\n"
+					+ "> * [Title 5](#title-5)\n"
 					+ "\n\n\nthis is a fake text done for testing.\n\n# Title 1\n\nthis is a fake "
 					+ "text done for testing. this is a fake text done for testing. this is a\n\n## Title 2\n"
 					+ "\nfake text done for testing. this is a fake text\n\n### Title 3\n\n## Title 4\n"
@@ -180,7 +199,8 @@ public void outline02_level3() throws Exception {
 			String value = this.parser.transform(file);
 			assertEquals("# Title\n\n## Title 0\n\nthis is a fake text done for testing. this is a fake text "
 					+ "done for testing. this is a fake text done for testing.\n\n\n"
-					+ "* [Title 3](#title-3)\n\n\n\nthis is a fake text done for testing.\n\n# Title 1\n\nthis is a fake "
+					+ "> * [Title 3](#title-3)\n"
+					+ "\n\n\nthis is a fake text done for testing.\n\n# Title 1\n\nthis is a fake "
 					+ "text done for testing. this is a fake text done for testing. this is a\n\n## Title 2\n"
 					+ "\nfake text done for testing. this is a fake text\n\n### Title 3\n\n## Title 4\n"
 					+ "\n## Title 5\n\ndone for testing. this is a fake text done\nfor testing. this is a "
@@ -199,87 +219,11 @@ public void hrefMapping01() throws Exception {
 					value);
 		}
 
-		@Test(expected = ParsingException.class)
-		public void invalidLocalHref() throws Exception {
-			File file = file("invalidhref.txt");
-			this.parser.transform(file);
-		}
-
 		@Test
 		public void image01() throws Exception {
 			File file = file("image.txt");
 			String value = this.parser.transform(file);
-			assertEquals("My link to [local MD file](./outline.html)\n\nMy link to [local file](./outline.txt)\n\n"
-					+ "My link to [remote file](http://www.sarl.io)",
-					value);
-		}
-
-		@Test(expected = ParsingException.class)
-		public void invalidImage() throws Exception {
-			File file = file("invalidimg.txt");
-			this.parser.transform(file);
-		}
-
-	}
-
-	public static class ValidationTest {
-
-		private MarkdownParser parser;
-
-		@Before
-		public void setUp() {
-			Injector injector = SARLStandaloneSetup.doSetup();
-			this.parser = injector.getInstance(MarkdownParser.class);
-		}
-
-		@Test
-		public void success01() {
-
-		}
-
-		@Test
-		public void failure01() {
-
-		}
-
-		@Test
-		public void fact01() {
-
-		}
-
-		@Test
-		public void successFailureFact01() {
-
-		}
-
-		@Test
-		public void referenceToLocalFile01() {
-
-		}
-
-		@Test
-		public void referenceToLocalMdFile01() {
-
-		}
-
-		@Test
-		public void referenceToMissedLocalFile01() {
-
-		}
-
-		@Test
-		public void referenceToRemoteFile01() {
-
-		}
-
-		@Test
-		public void image01() {
-
-		}
-
-		@Test
-		public void missedImage01() {
-
+			assertEquals("My link to ![local MD file](./outline.md)", value);
 		}
 
 	}

tests/io.sarl.maven.docs.generator.tests/src/test/java/io/sarl/maven/docs/generator/tests/parser/SarlDocumentationParserTest.java

@@ -34,6 +34,7 @@
 import org.apache.commons.lang3.tuple.MutablePair;
 import org.apache.commons.lang3.tuple.MutableTriple;
 import org.arakhne.afc.vmutil.FileSystem;
+import org.eclipse.xtext.util.Strings;
 import org.junit.Before;
 import org.junit.Test;
 import org.junit.runner.RunWith;
@@ -76,6 +77,7 @@ public static class TransformTest {
 		public void setUp() {
 			Injector injector = SARLStandaloneSetup.doSetup();
 			this.parser = injector.getInstance(SarlDocumentationParser.class);
+			this.parser.setBlockCodeTemplate(SarlDocumentationParser.getBasicCodeBlockFormatter());
 		}
 
 		@Test(expected = ParsingException.class)
@@ -233,7 +235,7 @@ public void onOff01() throws Exception {
 			assertEquals("this is a fake text done for testing. this is a fake text done for testing. this is a fake "
 					+ "text done for testing.\n\nthis is a fake text done for testing. this is a fake text done for "
 					+ "testing. this is a fake text done for testing. this is a fake text done for testing.\n\n"
-					+ "```\nof code\n```\n\nthis is a fake text done for testing. this is a fake text done for "
+					+ "\tof code\n\n\nthis is a fake text done for testing. this is a fake text done for "
 					+ "testing. this is a fake text done for testing. this is a fake text done for testing. this is "
 					+ "a fake text done \nfor testing. this is a fake text done for testing. this is a fake text "
 					+ "done for testing. this is a fake text done\nfor testing. this is a fake text done for testing. "
@@ -248,7 +250,7 @@ public void onOff02() throws Exception {
 			assertEquals("this is a fake text done for testing. this is a fake text done for testing. this is a fake "
 					+ "text done for testing.\n\nthis is a fake text done for testing. this is a fake text done for "
 					+ "testing. this is a fake text done for testing. this is a fake text done for testing.\n\n"
-					+ "```\nof code\n```\n\nthis is a fake text done for testing. this is a fake text done for "
+					+ "\tof code\n\n\nthis is a fake text done for testing. this is a fake text done for "
 					+ "testing. this is a fake text done for testing. this is a fake text done for testing. this is "
 					+ "a fake text done \nfor testing. this is a fake text done for testing. this is a fake text "
 					+ "done for testing. this is a fake text done\nfor testing. this is a fake text done for testing. "
@@ -266,6 +268,7 @@ public static class ValidationTest {
 		public void setUp() {
 			Injector injector = SARLStandaloneSetup.doSetup();
 			this.parser = injector.getInstance(SarlDocumentationParser.class);
+			this.parser.setBlockCodeTemplate(SarlDocumentationParser.getBasicCodeBlockFormatter());
 		}
 
 		@Test
@@ -362,9 +365,9 @@ public void successFailureFact01() {
 						+ "				info(\"Hello\")\n"
 						+ "			}\n"
 						+ "		}",
-						values.get(0));
+						values.get(0).getRight());
 				assertEquals("agent MyAgent {}",
-						values.get(1));
+						values.get(1).getRight());
 			});
 		}