Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorStéphane Bégaudeau2016-05-19 09:31:35 -0400
committerStephane Begaudeau2016-05-24 04:06:37 -0400
commit21e30c4d28253259fd06ac1302d82ffd7a520ee7 (patch)
tree7abf74e03a3f2ab3fabac47c002de640f1f43c12 /doc/org.eclipse.eef.documentation.export
parentba2fa5a65ff0fd7f2218ff1b501fccd882bb31ee (diff)
downloadorg.eclipse.eef-21e30c4d28253259fd06ac1302d82ffd7a520ee7.tar.gz
org.eclipse.eef-21e30c4d28253259fd06ac1302d82ffd7a520ee7.tar.xz
org.eclipse.eef-21e30c4d28253259fd06ac1302d82ffd7a520ee7.zip
Improve the documentation
1) The css of the image has now a version number to ensure that future update of the documentation will not create any issue. 2) A breadcrumb is now added during the export. This breadcrumb is computed from the toc.xml file from the documentation bundle. Change-Id: I4637dba0fe4a0ab61dd2953dbb4797045e206d05 Signed-off-by: Stéphane Bégaudeau <stephane.begaudeau@obeo.fr>
Diffstat (limited to 'doc/org.eclipse.eef.documentation.export')
-rw-r--r--doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/Exporter.java123
-rw-r--r--doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/ExporterTests.java6
-rw-r--r--doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/TocReader.java113
-rw-r--r--doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/Topic.java119
4 files changed, 357 insertions, 4 deletions
diff --git a/doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/Exporter.java b/doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/Exporter.java
index 52f199112..59de08bf2 100644
--- a/doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/Exporter.java
+++ b/doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/Exporter.java
@@ -13,6 +13,7 @@ package org.eclipse.eef.documentation.export.internal;
import static org.junit.Assert.fail;
import com.google.common.base.Charsets;
+import com.google.common.collect.Lists;
import com.google.common.io.ByteStreams;
import com.google.common.io.CharStreams;
import com.google.common.io.Closeables;
@@ -28,6 +29,7 @@ import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.Enumeration;
+import java.util.Iterator;
import java.util.List;
import org.eclipse.core.runtime.Platform;
@@ -111,6 +113,11 @@ public class Exporter {
public static final String ROOT_DOCUMENTATION_ASSET_URL = "sections/documentation/"; //$NON-NLS-1$
/**
+ * The path of the toc.xml file.
+ */
+ public static final String TOC_XML_PATH = "/pages/toc.xml"; //$NON-NLS-1$
+
+ /**
* Exports the documentation for the website.
*/
@Test
@@ -118,6 +125,7 @@ public class Exporter {
Bundle bundle = Platform.getBundle("org.eclipse.eef.documentation"); //$NON-NLS-1$
if (bundle != null) {
String version = this.getVersion(bundle);
+ List<Topic> topics = this.getTopics(bundle);
// Find all the documentation pages recursively in the documentation bundle
Enumeration<URL> entries = bundle.findEntries(DOCUMENTATION_PAGES_ROOT_PATH, "*.*", true); //$NON-NLS-1$
@@ -125,10 +133,12 @@ public class Exporter {
URL entry = entries.nextElement();
String path = entry.getPath().substring((DOCUMENTATION_PAGES_ROOT_PATH + "/").length()); //$NON-NLS-1$
+ List<Topic> breadcrumbTopics = this.getBreadcrumbTopics(topics, path);
+
if (entry.getFile().endsWith(HTML_EXTENSION)) {
// Read, process and write the processed HTML files
List<String> lines = this.readLines(entry);
- List<String> linesToKeep = this.getBody(lines, path, version);
+ List<String> linesToKeep = this.getBody(lines, path, version, breadcrumbTopics);
this.writeLines(linesToKeep, path, version);
} else if (this.shouldCopy(path)) {
// Let's copy other resources directly at its new location (images, video, etc)
@@ -138,6 +148,68 @@ public class Exporter {
}
}
+ public List<Topic> getBreadcrumbTopics(List<Topic> topics, String path) {
+ List<Topic> breadcrumbTopics = new ArrayList<>();
+
+ // Find the topic matching the path
+ Topic topic = this.find(topics, path);
+
+ // Compute its parent topics
+ if (topic != null) {
+ breadcrumbTopics.addAll(this.getParents(topic));
+ }
+
+ return Lists.reverse(breadcrumbTopics);
+ }
+
+ private List<Topic> getParents(Topic topic) {
+ List<Topic> parents = new ArrayList<>();
+
+ if (topic.getParent() != null) {
+ parents.add(topic.getParent());
+ parents.addAll(this.getParents(topic.getParent()));
+ }
+
+ return parents;
+ }
+
+ private Topic find(List<Topic> topics, String path) {
+ Topic topic = null;
+
+ Iterator<Topic> iterator = topics.iterator();
+ while (topic == null && iterator.hasNext()) {
+ Topic next = iterator.next();
+ if (("pages/" + path).equals(next.getHref())) { //$NON-NLS-1$
+ topic = next;
+ } else {
+ topic = this.find(next.getTopics(), path);
+ }
+ }
+ return topic;
+ }
+
+ public List<Topic> getTopics(Bundle bundle) {
+ List<Topic> topics = new ArrayList<>();
+ // Find the toc.xml file
+ URL tocXmlEntry = bundle.getEntry(TOC_XML_PATH);
+ if (tocXmlEntry != null) {
+ InputStream inputStream = null;
+ try {
+ inputStream = tocXmlEntry.openStream();
+ topics.addAll(new TocReader().getTopics(inputStream));
+ } catch (IOException e) {
+ fail(e.getMessage());
+ } finally {
+ try {
+ Closeables.close(inputStream, false);
+ } catch (IOException e) {
+ fail(e.getMessage());
+ }
+ }
+ }
+ return topics;
+ }
+
/**
* Indicates if we should copy the resource with the given path.
*
@@ -206,12 +278,18 @@ public class Exporter {
* The path of the file
* @param documentationVersion
* The version of the documentation
+ * @param breadcrumbTopics
+ * The breadcrumb topics
* @return The content of the file to save
*/
- public List<String> getBody(List<String> lines, String path, String documentationVersion) {
+ public List<String> getBody(List<String> lines, String path, String documentationVersion, List<Topic> breadcrumbTopics) {
List<String> linesToKeep = new ArrayList<>();
linesToKeep.add(ROOT_ELEMENT_START);
+ if (!"index.html".equalsIgnoreCase(path)) { //$NON-NLS-1$
+ List<String> breadcrumb = this.createBreadcrumb(breadcrumbTopics, documentationVersion);
+ linesToKeep.addAll(breadcrumb);
+ }
boolean hasFoundStartBody = false;
boolean hasFoundStopBody = false;
for (String line : lines) {
@@ -227,6 +305,45 @@ public class Exporter {
}
/**
+ * @param breadcrumbTopics
+ * @return
+ */
+ private List<String> createBreadcrumb(List<Topic> breadcrumbTopics, String documentationVersion) {
+ List<String> lines = new ArrayList<>();
+
+ lines.add(" <ul class=\"breadcrumb\">"); //$NON-NLS-1$
+ if (breadcrumbTopics.size() > 0) {
+ lines.add(" <li><a href=\"" + ROOT_DOCUMENTATION_URL + '/' + documentationVersion + "\">" + documentationVersion + "</a> <span class=\"divider\">/</span></li>"); //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$
+ } else {
+ lines.add(" <li><a href=\"" + ROOT_DOCUMENTATION_URL + '/' + documentationVersion + "\">" + documentationVersion + "</a></li>"); //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$
+ }
+ int i = 0;
+ for (Topic topic : breadcrumbTopics) {
+ String href = topic.getHref();
+
+ if (href.startsWith(DOCUMENTATION_PAGES_ROOT_PATH.substring(1))) {
+ href = href.substring(DOCUMENTATION_PAGES_ROOT_PATH.substring(1).length());
+ }
+ if (href.endsWith(HTML_EXTENSION)) {
+ href = href.substring(0, href.length() - HTML_EXTENSION.length());
+ }
+
+ href = ROOT_DOCUMENTATION_URL + '/' + documentationVersion + href;
+
+ if (i + 1 < breadcrumbTopics.size()) {
+ lines.add(" <li><a href=\"" + href + "\">" + topic.getLabel() + "</a> <span class=\"divider\">/</span></li>"); //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$
+ } else {
+ lines.add(" <li><a href=\"" + href + "\">" + topic.getLabel() + "</a></li>"); //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$
+ }
+
+ i = i + 1;
+ }
+ lines.add(" </ul>"); //$NON-NLS-1$
+
+ return lines;
+ }
+
+ /**
* Fixes the links that can be found in the line.
*
* @param line
@@ -277,7 +394,7 @@ public class Exporter {
/**
* Handles the image.
- *
+ *
* @param builder
* The builder
* @param line
diff --git a/doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/ExporterTests.java b/doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/ExporterTests.java
index 7c84aa11b..31f729f79 100644
--- a/doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/ExporterTests.java
+++ b/doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/ExporterTests.java
@@ -18,6 +18,7 @@ import static org.junit.Assert.assertTrue;
import com.google.common.collect.Lists;
+import java.util.ArrayList;
import java.util.List;
import org.junit.Test;
@@ -66,11 +67,14 @@ public class ExporterTests {
//@formatter:on
// Version and path can be null since we do not have any links
- List<String> actual = new Exporter().getBody(lines, null, null);
+ List<String> actual = new Exporter().getBody(lines, "/pages/language/page.html", "1.6.0", new ArrayList<>()); //$NON-NLS-1$ //$NON-NLS-2$
// The result must have a specific first and last line with only the body inside
List<String> expected = lines.subList(5, 9);
expected.add(0, Exporter.ROOT_ELEMENT_START);
+ expected.add(1, " <ul class=\"breadcrumb\">"); //$NON-NLS-1$
+ expected.add(2, " <li><a href=\"#/documentation/1.6.0\">1.6.0</a></li>"); //$NON-NLS-1$
+ expected.add(3, " </ul>"); //$NON-NLS-1$
expected.add(Exporter.ROOT_ELEMENT_END);
assertThat(actual, contains(expected.toArray(new String[expected.size()])));
diff --git a/doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/TocReader.java b/doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/TocReader.java
new file mode 100644
index 000000000..ee30b3d7e
--- /dev/null
+++ b/doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/TocReader.java
@@ -0,0 +1,113 @@
+/*******************************************************************************
+ * Copyright (c) 2016 Obeo.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ * Obeo - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.eef.documentation.export.internal;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+
+import javax.xml.parsers.DocumentBuilder;
+import javax.xml.parsers.DocumentBuilderFactory;
+import javax.xml.parsers.ParserConfigurationException;
+
+import org.w3c.dom.Document;
+import org.w3c.dom.Element;
+import org.w3c.dom.NamedNodeMap;
+import org.w3c.dom.Node;
+import org.w3c.dom.NodeList;
+import org.xml.sax.SAXException;
+
+/**
+ * Utility class used to parse the toc.xml to create the breadcrumb.
+ *
+ * @author sbegaudeau
+ */
+public class TocReader {
+ /**
+ * The name of the topic element.
+ */
+ public static final String TOPIC = "topic"; //$NON-NLS-1$
+ /**
+ * The URL of the topic.
+ */
+ public static final String HREF = "href"; //$NON-NLS-1$
+
+ /**
+ * The label of the topic.
+ */
+ public static final String LABEL = "label"; //$NON-NLS-1$
+
+ /**
+ * Parse the given XML content and return the list of topics found.
+ *
+ * @param inputStream
+ * The XML content of the toc.xml file
+ * @return The list of topics found in the toc.xml file
+ */
+ public List<Topic> getTopics(InputStream inputStream) {
+ List<Topic> topics = new ArrayList<>();
+
+ DocumentBuilderFactory documentBuilderFactory = DocumentBuilderFactory.newInstance();
+ try {
+ DocumentBuilder documentBuilder = documentBuilderFactory.newDocumentBuilder();
+ Document document = documentBuilder.parse(inputStream);
+ document.getDocumentElement().normalize();
+
+ Element element = document.getDocumentElement();
+ NodeList nodeList = element.getChildNodes();
+
+ topics.addAll(this.visitChildNodes(nodeList));
+ } catch (ParserConfigurationException | SAXException | IOException e) {
+ e.printStackTrace();
+ }
+
+ return topics;
+ }
+
+ /**
+ * @param nodeList
+ * @return
+ */
+ private Collection<Topic> visitChildNodes(NodeList nodeList) {
+ List<Topic> topics = new ArrayList<>();
+
+ for (int i = 0; i < nodeList.getLength(); i++) {
+ Node node = nodeList.item(i);
+ if (node.getNodeType() == Node.ELEMENT_NODE) {
+ Topic topic = new Topic();
+
+ if (node.hasAttributes()) {
+ NamedNodeMap attributes = node.getAttributes();
+ for (int j = 0; j < attributes.getLength(); j++) {
+ Node attribute = attributes.item(j);
+ if (HREF.equals(attribute.getNodeName())) {
+ topic.setHref(attribute.getNodeValue());
+ } else if (LABEL.equals(attribute.getNodeName())) {
+ topic.setLabel(attribute.getNodeValue());
+ }
+ }
+ }
+
+ if (node.hasChildNodes()) {
+ Collection<Topic> childTopics = this.visitChildNodes(node.getChildNodes());
+ topic.getTopics().addAll(childTopics);
+ childTopics.forEach(child -> child.setParent(topic));
+ }
+
+ topics.add(topic);
+ }
+ }
+
+ return topics;
+ }
+}
diff --git a/doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/Topic.java b/doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/Topic.java
new file mode 100644
index 000000000..35d69610c
--- /dev/null
+++ b/doc/org.eclipse.eef.documentation.export/src/org/eclipse/eef/documentation/export/internal/Topic.java
@@ -0,0 +1,119 @@
+/*******************************************************************************
+ * Copyright (c) 2016 Obeo.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ * Obeo - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.eef.documentation.export.internal;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.stream.Collectors;
+
+/**
+ * A POJO used to parse the toc.xml to create the breadcrumb of the website.
+ *
+ * @author sbegaudeau
+ */
+public class Topic {
+
+ /**
+ * The URL of the topic.
+ */
+ private String href;
+
+ /**
+ * The label of the topic.
+ */
+ private String label;
+
+ /**
+ * The parent topic.
+ */
+ private Topic parent;
+
+ /**
+ * The child topics.
+ */
+ private List<Topic> topics = new ArrayList<>();
+
+ /**
+ * Return the href.
+ *
+ * @return the href
+ */
+ public String getHref() {
+ return this.href;
+ }
+
+ /**
+ * Sets the href.
+ *
+ * @param href
+ * the href to set
+ */
+ public void setHref(String href) {
+ this.href = href;
+ }
+
+ /**
+ * Return the label.
+ *
+ * @return the label
+ */
+ public String getLabel() {
+ return this.label;
+ }
+
+ /**
+ * Sets the label.
+ *
+ * @param label
+ * the label to set
+ */
+ public void setLabel(String label) {
+ this.label = label;
+ }
+
+ /**
+ * Return the topics.
+ *
+ * @return the topics
+ */
+ public List<Topic> getTopics() {
+ return this.topics;
+ }
+
+ /**
+ * Sets the parent.
+ *
+ * @param parent
+ * the parent to set
+ */
+ public void setParent(Topic parent) {
+ this.parent = parent;
+ }
+
+ /**
+ * Return the parent.
+ *
+ * @return the parent
+ */
+ public Topic getParent() {
+ return this.parent;
+ }
+
+ /**
+ * {@inheritDoc}
+ *
+ * @see java.lang.Object#toString()
+ */
+ @Override
+ public String toString() {
+ return "Topic [href=" + this.href + ", label=" + this.label + ", children=" + this.topics.stream().map(Object::toString).collect(Collectors.toList()) + "]"; //$NON-NLS-1$//$NON-NLS-2$//$NON-NLS-3$ //$NON-NLS-4$
+ }
+}

Back to the top