From 0261196298033a7e4a1d30526efb590032a19591 Mon Sep 17 00:00:00 2001 From: Dan Willemsen Date: Mon, 26 Feb 2018 14:37:28 -0800 Subject: Add droiddoc_template module for templates-sdk Test: m core-docs Change-Id: I441ca5745a06a81b1ea8352e65975416a0c24e28 --- Android.bp | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Android.bp b/Android.bp index 18104ff..7f9f571 100644 --- a/Android.bp +++ b/Android.bp @@ -12,6 +12,11 @@ // See the License for the specific language governing permissions and // limitations under the License. +droiddoc_template { + name: "droiddoc-templates-sdk", + path: "res/assets/templates-sdk", +} + java_library_host { name: "doclava", srcs: [ -- cgit v1.2.3 From 5880fe8bc7736d15dd4d2d98293bdaf330ca115d Mon Sep 17 00:00:00 2001 From: Scott Main Date: Mon, 18 Dec 2017 14:20:27 -0800 Subject: Add support to build a full _book.yaml file for DAC reference. This creates a new version of writeYamlTree() to reproduce the nav structure used on d.android.com with all API links. Previously, we generated a book.yaml for dac that included only the package names. All classes/interfaces were added to the nav with JS. Although Doclava already included an option to generate the complete book.yaml file (used by other javadoc projects for DevSite), this book.yaml file did not organize pages by type (classes, interfaces, etc) and it put nested classes behind a zippy, below the parent class. Whereas we prefer to show all classes within a package as siblings. So this new writeYamlTree2() method uses the same Node list used by the original JS implementation, but with new rendering methods to create a yaml structure instead of a JS array for all API links. To use this new book.yaml format, the doclava command must include the `yamlV2` option. Then, you'll actually receive 2 yaml files: the traditional "v1" yaml file and the new v2 yaml file prefixed with "NEW" in the filename. This is particularly important for DAC right now so that we can submit this change to Git without affecting the expected yaml file for the site. To support the "Irina" version of DAC, we simply rename the "NEW" file to replace the legacy version. This also uses the new book.yaml property "version_added" to specify the "since" API level for each API (instead of the "status_text" property that applied as a CSS class). Once we migrate fully to Irina, we can disable this dual output. Example output is shown in http://cl/187393231 bug: b/69845924, b/70844489 test: make ds-docs Change-Id: I6e98ee05bb406863a7c60e6bfe56ca745ac83f10 --- res/assets/templates-sdk/yaml_navtree2.cs | 15 +++++ src/com/google/doclava/Doclava.java | 12 ++++ src/com/google/doclava/NavTree.java | 105 +++++++++++++++++++++++++++++- 3 files changed, 131 insertions(+), 1 deletion(-) create mode 100644 res/assets/templates-sdk/yaml_navtree2.cs diff --git a/res/assets/templates-sdk/yaml_navtree2.cs b/res/assets/templates-sdk/yaml_navtree2.cs new file mode 100644 index 0000000..a8ec241 --- /dev/null +++ b/res/assets/templates-sdk/yaml_navtree2.cs @@ -0,0 +1,15 @@ +toc: + +- title: Class Index + path: / + status_text: no-toggle +- title: Package Index + path: / + status_text: no-toggle + \ No newline at end of file diff --git a/src/com/google/doclava/Doclava.java b/src/com/google/doclava/Doclava.java index e1c92f1..fe29f2b 100644 --- a/src/com/google/doclava/Doclava.java +++ b/src/com/google/doclava/Doclava.java @@ -118,6 +118,7 @@ public class Doclava { public static Map annotationDocumentationMap = null; public static boolean referenceOnly = false; public static boolean staticOnly = false; + public static boolean yamlV2 = false; /* whether to build the new version of the yaml file */ public static AuxSource auxSource = new EmptyAuxSource(); public static Linter linter = new EmptyLinter(); public static boolean android = false; @@ -355,6 +356,8 @@ public class Doclava { NAVTREE_ONLY = true; } else if (a[0].equals("-atLinksNavtree")) { AT_LINKS_NAVTREE = true; + } else if (a[0].equals("-yamlV2")) { + yamlV2 = true; } else if (a[0].equals("-devsite")) { // Don't copy any assets to devsite output includeAssets = false; @@ -496,6 +499,12 @@ public class Doclava { // Write yaml tree. if (yamlNavFile != null){ NavTree.writeYamlTree(javadocDir, yamlNavFile); + if (yamlV2) { + // Generate both for good measure, to make transitions easier, but change the filename + // for the new one so there's yet another explicit opt-in required by fixing the name. + yamlNavFile = "_NEW" + yamlNavFile; + NavTree.writeYamlTree2(javadocDir, yamlNavFile); + } } // Packages Pages @@ -728,6 +737,9 @@ public class Doclava { if (option.equals("-devsite")) { return 1; } + if (option.equals("-yamlV2")) { + return 1; + } if (option.equals("-dac_libraryroot")) { return 2; } diff --git a/src/com/google/doclava/NavTree.java b/src/com/google/doclava/NavTree.java index 5d055db..ee7dbde 100644 --- a/src/com/google/doclava/NavTree.java +++ b/src/com/google/doclava/NavTree.java @@ -59,6 +59,40 @@ public class NavTree { /** * Write the YAML formatted navigation tree. + * This is intended to replace writeYamlTree(), but for now requires an explicit opt-in via + * the yamlV2 flag in the doclava command. This version creates a yaml file with all classes, + * interface, exceptions, etc. separated into collapsible groups. + */ + public static void writeYamlTree2(String dir, String fileName){ + List children = new ArrayList(); + for (PackageInfo pkg : Doclava.choosePackages()) { + children.add(makePackageNode(pkg)); + } + Node node = new Node("Reference", Doclava.ensureSlash(dir) + "packages.html", children, null); + StringBuilder buf = new StringBuilder(); + + node.renderChildrenYaml(buf, 0); + + Data data = Doclava.makeHDF(); + data.setValue("reference_tree", buf.toString()); + + if (Doclava.USE_DEVSITE_LOCALE_OUTPUT_PATHS && (Doclava.libraryRoot != null)) { + dir = Doclava.ensureSlash(dir) + Doclava.libraryRoot; + } + + data.setValue("docs.classes.link", Doclava.ensureSlash(dir) + "classes.html"); + data.setValue("docs.packages.link", Doclava.ensureSlash(dir) + "packages.html"); + + ClearPage.write(data, "yaml_navtree2.cs", Doclava.ensureSlash(dir) + fileName); + + } + + + /** + * Write the YAML formatted navigation tree (legacy version). + * This creates a yaml file with package names followed by all + * classes, interfaces, exceptions, etc. But they are not separated by classes, interfaces, etc. + * It also nests any nested classes under the parent class, instead of listing them as siblings. * @see "http://yaml.org/" */ public static void writeYamlTree(String dir, String fileName){ @@ -253,5 +287,74 @@ public class NavTree { renderString(buf, mArtifact); buf.append(" ]"); } + + + // YAML VERSION + + + static void renderStringYaml(StringBuilder buf, String s) { + if (s != null) { + final int N = s.length(); + for (int i = 0; i < N; i++) { + char c = s.charAt(i); + if (c >= ' ' && c <= '~' && c != '"' && c != '\\') { + buf.append(c); + } else { + buf.append("\\u"); + for (int j = 0; i < 4; i++) { + char x = (char) (c & 0x000f); + if (x >= 10) { + x = (char) (x - 10 + 'a'); + } else { + x = (char) (x + '0'); + } + buf.append(x); + c >>= 4; + } + } + } + } + } + void renderChildrenYaml(StringBuilder buf, int depth) { + List list = mChildren; + if (list != null && list.size() > 0) { + if (depth > 0) { + buf.append("\n\n" + getIndent(depth)); + buf.append("section:"); + } + final int N = list.size(); + for (int i = 0; i < N; i++) { + // get each child Node and render it + list.get(i).renderYaml(buf, depth); + } + // Extra line break after each "section" + buf.append("\n"); + } + } + void renderYaml(StringBuilder buf, int depth) { + buf.append("\n" + getIndent(depth)); + buf.append("- title: \""); + renderStringYaml(buf, mLabel); + buf.append("\""); + // Add link path, if it exists (the class/interface toggles don't have links) + if (mLink != null) { + buf.append("\n" + getIndent(depth)); + buf.append(" path: "); + renderStringYaml(buf, "/" + mLink); + // and the API level also only makes sense if there's a link + buf.append("\n" + getIndent(depth)); + buf.append(" version_added: "); + renderStringYaml(buf, mSince); + } + // try rendering child Nodes + renderChildrenYaml(buf, depth + 1); + } + String getIndent(int depth) { + String spaces = ""; + for (int i = 0; i < depth; i++) { + spaces += " "; + } + return spaces; + } } -} +} \ No newline at end of file -- cgit v1.2.3