Examples with SkylarkModuleDoc com.google.devtools.build.docgen.skylark.SkylarkModuleDoc used on opensource projects

Example 6 with SkylarkModuleDoc

use of com.google.devtools.build.docgen.skylark.SkylarkModuleDoc in project bazel by bazelbuild.

the class SkylarkDocumentationTest method checkSkylarkTopLevelEnvItemsAreDocumented.

@SuppressWarnings("unchecked")
private void checkSkylarkTopLevelEnvItemsAreDocumented(Environment env) throws Exception {
    Map<String, String> docMap = new HashMap<>();
    Map<String, SkylarkModuleDoc> modules = SkylarkDocumentationCollector.collectModules();
    SkylarkModuleDoc topLevel = modules.remove(SkylarkDocumentationCollector.getTopLevelModule().name());
    for (Entry<String, SkylarkBuiltinMethodDoc> entry : topLevel.getBuiltinMethods().entrySet()) {
        docMap.put(entry.getKey(), entry.getValue().getDocumentation());
    }
    for (Entry<String, SkylarkModuleDoc> entry : modules.entrySet()) {
        docMap.put(entry.getKey(), entry.getValue().getDocumentation());
    }
    List<String> undocumentedItems = new ArrayList<>();
    // All built in variables are registered in the Skylark global environment.
    for (String varname : env.getVariableNames()) {
        if (docMap.containsKey(varname)) {
            if (docMap.get(varname).isEmpty()) {
                undocumentedItems.add(varname);
            }
        } else {
            undocumentedItems.add(varname);
        }
    }
    assertWithMessage("Undocumented Skylark Environment items: " + undocumentedItems).that(undocumentedItems).isEmpty();
}

Example 7 with SkylarkModuleDoc

use of com.google.devtools.build.docgen.skylark.SkylarkModuleDoc in project bazel by bazelbuild.

the class SkylarkDocumentationProcessor method findGlobalModule.

private static SkylarkModuleDoc findGlobalModule(Map<SkylarkModuleCategory, List<SkylarkModuleDoc>> modulesByCategory) {
    List<SkylarkModuleDoc> topLevelModules = modulesByCategory.get(SkylarkModuleCategory.TOP_LEVEL_TYPE);
    String globalModuleName = SkylarkDocumentationCollector.getTopLevelModule().name();
    for (SkylarkModuleDoc module : topLevelModules) {
        if (module.getName().equals(globalModuleName)) {
            return module;
        }
    }
    throw new IllegalStateException("No globals module in the top level category.");
}

Example 8 with SkylarkModuleDoc

use of com.google.devtools.build.docgen.skylark.SkylarkModuleDoc in project bazel by bazelbuild.

the class SkylarkDocumentationCollector method collectModules.

/**
   * Collects the documentation for all Skylark modules and returns a map that maps Skylark module
   * name to the module documentation.
   *
   * <p>WARNING: This method no longer supports the specification of additional module classes via
   * parameters. Instead, all module classes are being picked up automatically.
   *
   * @param clazz DEPRECATED.
   */
public static Map<String, SkylarkModuleDoc> collectModules(@Deprecated String... clazz) throws ClassPathException {
    Map<String, SkylarkModuleDoc> modules = new TreeMap<>();
    Map<SkylarkModule, Class<?>> builtinModules = new HashMap<>();
    for (Class<?> candidateClass : Classpath.findClasses(MODULES_PACKAGE_PREFIX)) {
        SkylarkModule annotation = candidateClass.getAnnotation(SkylarkModule.class);
        if (annotation != null) {
            collectBuiltinModule(builtinModules, candidateClass);
            collectJavaObjects(annotation, candidateClass, modules);
        }
        collectBuiltinDoc(modules, candidateClass.getDeclaredFields());
    }
    return modules;
}

Example 9 with SkylarkModuleDoc

use of com.google.devtools.build.docgen.skylark.SkylarkModuleDoc in project bazel by bazelbuild.

the class SkylarkDocumentationProcessor method generateDocumentation.

/** Generates the Skylark documentation to the given output directory. */
public static void generateDocumentation(String outputDir, String... clazz) throws IOException, ClassPathException {
    Map<String, SkylarkModuleDoc> modules = SkylarkDocumentationCollector.collectModules(clazz);
    // Generate the top level module first in the doc
    SkylarkModuleDoc topLevelModule = modules.remove(SkylarkDocumentationCollector.getTopLevelModule().name());
    writePage(outputDir, topLevelModule);
    Map<SkylarkModuleCategory, List<SkylarkModuleDoc>> modulesByCategory = new HashMap<>();
    for (SkylarkModuleCategory c : SkylarkModuleCategory.values()) {
        modulesByCategory.put(c, new ArrayList<SkylarkModuleDoc>());
    }
    modulesByCategory.get(topLevelModule.getAnnotation().category()).add(topLevelModule);
    for (SkylarkModuleDoc module : modules.values()) {
        if (module.getAnnotation().documented()) {
            writePage(outputDir, module);
            modulesByCategory.get(module.getAnnotation().category()).add(module);
        }
    }
    writeCategoryPage(SkylarkModuleCategory.CONFIGURATION_FRAGMENT, outputDir, modulesByCategory);
    writeCategoryPage(SkylarkModuleCategory.BUILTIN, outputDir, modulesByCategory);
    writeCategoryPage(SkylarkModuleCategory.PROVIDER, outputDir, modulesByCategory);
    writeNavPage(outputDir, modulesByCategory.get(SkylarkModuleCategory.TOP_LEVEL_TYPE));
    // In the code, there are two SkylarkModuleCategory instances that have no heading:
    // TOP_LEVEL_TYPE and NONE.
    // TOP_LEVEL_TYPE also contains the "global" module.
    // We remove both categories and the "global" module from the map and display them manually:
    // - Methods in the "global" module are displayed under "Global Methods and Constants".
    // - Modules in both categories are displayed under "Global Modules" (except for the global
    // module itself).
    List<String> globalFunctions = new ArrayList<>();
    SkylarkModuleDoc globalModule = findGlobalModule(modulesByCategory);
    for (SkylarkMethodDoc method : globalModule.getMethods()) {
        if (method.documented()) {
            globalFunctions.add(method.getName());
        }
    }
    List<String> globalModules = new ArrayList<>();
    for (SkylarkModuleCategory globalCategory : GLOBAL_CATEGORIES) {
        List<SkylarkModuleDoc> allGlobalModules = modulesByCategory.remove(globalCategory);
        for (SkylarkModuleDoc module : allGlobalModules) {
            if (!module.getName().equals(globalModule.getName())) {
                globalModules.add(module.getName());
            }
        }
    }
    Collections.sort(globalModules);
    writeOverviewPage(outputDir, globalModule.getName(), globalFunctions, globalModules, modulesByCategory);
}