Infrastructure for enso --docs option & signature generator

engine/polyglot-api/src/main/scala/org/enso/polyglot/Module.scala

@@ -44,14 +44,6 @@ class Module(private val value: Value) {
   def evalExpression(code: String): Value =
     value.invokeMember(EVAL_EXPRESSION, code)
 
-  /** Triggers generation of documentation from module sources.
-    *
-    * @return value with `GENERATE_DOCS` invoked on it.
-    */
-  def generateDocs(): Value = {
-    value.invokeMember(GENERATE_DOCS)
-  }
-
   /** Triggers gathering of import statements from module sources.
     *
     * @return value with `GATHER_IMPORT_STATEMENTS` invoked on it.

engine/polyglot-api/src/main/scala/org/enso/polyglot/TopScope.scala

@@ -34,7 +34,11 @@ class TopScope(private val value: Value) {
     value.invokeMember(UNREGISTER_MODULE, qualifiedName): Unit
   }
 
-  def compile(shouldCompileDependencies: Boolean): Unit = {
-    value.invokeMember(COMPILE, shouldCompileDependencies)
+  def compile(
+    shouldCompileDependencies: Boolean,
+    generateDocs: Boolean = false
+  ): Unit = {
+    value.invokeMember(COMPILE, shouldCompileDependencies, generateDocs)
   }
+
 }

engine/runner/src/main/java/org/enso/runner/Main.java

@@ -627,7 +627,7 @@ private void compile(
 
     var topScope = context.getTopScope();
     try {
-      topScope.compile(shouldCompileDependencies);
+      topScope.compile(shouldCompileDependencies, false);
       throw exitSuccess();
     } catch (Throwable t) {
       logger.error("Unexpected internal error", t);
@@ -772,16 +772,8 @@ private void generateDocsFrom(
 
     if (main.exists(x -> x.exists())) {
       var mainFile = main.get();
-      var mainModuleName = pkg.get().moduleNameForFile(mainFile).toString();
       var topScope = executionContext.getTopScope();
-      var mainModule = topScope.getModule(mainModuleName);
-      var generated = mainModule.generateDocs();
-      println(generated.toString());
-
-      // TODO:
-      // - go through executed code and get all HTML docs
-      //   with their corresponding atoms/methods etc.
-      // - Save those to files
+      topScope.compile(false, true);
     }
   }
 

engine/runtime-compiler/src/main/java/org/enso/compiler/dump/GenerateDocs.java

@@ -0,0 +1,71 @@
+package org.enso.compiler.dump;
+
+import java.io.IOException;
+import org.enso.compiler.context.CompilerContext;
+import org.enso.compiler.core.ir.module.scope.Definition;
+import org.enso.compiler.core.ir.module.scope.definition.Method;
+import org.enso.compiler.pass.resolve.DocumentationComments;
+import org.enso.compiler.pass.resolve.DocumentationComments$;
+import org.enso.filesystem.FileSystem;
+import scala.collection.immutable.Seq;
+import scala.jdk.CollectionConverters;
+
+/** Generator of documentation for an Enso project. */
+public final class GenerateDocs {
+  private GenerateDocs() {}
+
+  /**
+   * Iterate over all provide modules and generate documentation using {@code pkg}'s {@link
+   * FileSystem}.
+   *
+   * @param <File> abstract file to operate with
+   * @param pkg library to generate the documentation for
+   * @param modules parsed modules found in the library
+   * @throws IOException when I/O problem occurs
+   */
+  public static <File> void write(
+      org.enso.pkg.Package<File> pkg, Iterable<CompilerContext.Module> modules) throws IOException {
+    var fs = pkg.fileSystem();
+    var docs = fs.getChild(pkg.root(), "docs");
+    var api = fs.getChild(docs, "api");
+    fs.createDirectories(api);
+
+    for (var module : modules) {
+      var ir = module.getIr();
+      assert ir != null : "need IR for " + module;
+      var md = fs.getChild(api, module.getName() + ".md");
+      DONE:
+      try (var w = fs.newBufferedWriter(md)) {
+        w.append("## Documentation for " + module.getName() + "\n");
+
+        if (ir.isPrivate()) {
+          w.append("This module is **private**!\n");
+          break DONE;
+        }
+
+        for (var b : asJava(ir.bindings())) {
+          switch (b) {
+            case Definition.Type t -> w.append("#### **type** " + t.name().name() + "\n");
+            case Definition.Data d -> w.append("#### data " + d.name().name() + "\n");
+            case Definition.SugaredType s -> w.append("#### sugar " + s.name().name() + "\n");
+            case Method.Explicit m -> w.append("#### method " + m.methodName().name() + "\n");
+            case Method.Conversion c -> w.append("#### conversion " + c.methodName().name() + "\n");
+            default -> throw new AssertionError("unknown type " + b.getClass());
+          }
+          var option = b.passData().get(DocumentationComments$.MODULE$);
+          if (option.isDefined()) {
+            var doc = (DocumentationComments.Doc) option.get();
+            w.append(doc.documentation());
+            w.append("\n\n\n");
+          }
+        }
+      }
+    }
+
+    System.out.println("Documentation generated into " + api);
+  }
+
+  private static <T> Iterable<T> asJava(Seq<T> seq) {
+    return CollectionConverters.IterableHasAsJava(seq).asJava();
+  }
+}

engine/runtime-compiler/src/main/scala/org/enso/compiler/Compiler.scala

@@ -1,5 +1,6 @@
 package org.enso.compiler
 
+import scala.jdk.CollectionConverters.IterableHasAsJava
 import org.enso.compiler.context.{
   CompilerContext,
   FreshNameSupply,
@@ -139,7 +140,8 @@ class Compiler(
     */
   def compile(
     shouldCompileDependencies: Boolean,
-    useGlobalCacheLocations: Boolean
+    useGlobalCacheLocations: Boolean,
+    generateDocs: Boolean
   ): Future[java.lang.Boolean] = {
     getPackageRepository.getMainProjectPackage match {
       case None =>
@@ -181,6 +183,11 @@ class Compiler(
               shouldCompileDependencies
             )
 
+            if (generateDocs) {
+              org.enso.compiler.dump.GenerateDocs
+                .write(pkg, packageModules.asJava)
+            }
+
             context.serializeLibrary(
               this,
               pkg.libraryName,
@@ -198,8 +205,7 @@ class Compiler(
     initialize()
     parseModule(
       module,
-      irCachingEnabled && !context.isInteractive(module),
-      isGenDocs = true
+      irCachingEnabled && !context.isInteractive(module)
     )
     module
   }
@@ -537,8 +543,7 @@ class Compiler(
 
   private def parseModule(
     module: Module,
-    useCaches: Boolean,
-    isGenDocs: Boolean = false
+    useCaches: Boolean
   ): Unit = {
     context.log(
       Compiler.defaultLogLevel,
@@ -553,7 +558,7 @@ class Compiler(
       }
     }
 
-    uncachedParseModule(module, isGenDocs)
+    uncachedParseModule(module)
   }
 
   /** Retrieve module bindings from cache, if available.
@@ -570,7 +575,7 @@ class Compiler(
     } else None
   }
 
-  private def uncachedParseModule(module: Module, isGenDocs: Boolean): Unit = {
+  private def uncachedParseModule(module: Module): Unit = {
     context.log(
       Compiler.defaultLogLevel,
       "Loading module [{0}] from source.",
@@ -579,10 +584,9 @@ class Compiler(
     context.updateModule(module, _.resetScope())
 
     val moduleContext = ModuleContext(
-      module           = module,
-      freshNameSupply  = Some(freshNameSupply),
-      compilerConfig   = config,
-      isGeneratingDocs = isGenDocs
+      module          = module,
+      freshNameSupply = Some(freshNameSupply),
+      compilerConfig  = config
     )
 
     val src  = context.getCharacters(module)

engine/runtime-compiler/src/main/scala/org/enso/compiler/context/ModuleContext.scala

@@ -21,7 +21,6 @@ case class ModuleContext(
   compilerConfig: CompilerConfig,
   freshNameSupply: Option[FreshNameSupply]     = None,
   passConfiguration: Option[PassConfiguration] = None,
-  isGeneratingDocs: Boolean                    = false,
   pkgRepo: Option[PackageRepository]           = None
 ) {
   def isSynthetic(): Boolean          = module.isSynthetic()

engine/runtime/src/main/java/org/enso/interpreter/EnsoLanguage.java

@@ -240,7 +240,6 @@ protected ExecutableNode parse(InlineParsingRequest request) throws InlineParsin
               redirectConfigWithStrictErrors,
               scala.Option.empty(),
               scala.Option.empty(),
-              false,
               scala.Option.empty());
       var inlineContext =
           new InlineContext(

engine/runtime/src/main/java/org/enso/interpreter/runtime/Module.java

@@ -652,7 +652,10 @@ private static Object evalExpression(
     }
 
     private static Object generateDocs(Module module, EnsoContext context) {
-      return context.getCompiler().generateDocs(module.asCompilerModule());
+      var compilerModule = module.asCompilerModule();
+      var res = context.getCompiler().generateDocs(compilerModule);
+      assert res == compilerModule;
+      return module;
     }
 
     @CompilerDirectives.TruffleBoundary

engine/runtime/src/main/java/org/enso/interpreter/runtime/scope/TopLevelScope.java

@@ -173,9 +173,24 @@ private static Object leakContext(EnsoContext context) {
     private static Object compile(Object[] arguments, EnsoContext context)
         throws UnsupportedTypeException, ArityException {
       boolean useGlobalCache = context.isUseGlobalCache();
-      boolean shouldCompileDependencies = Types.extractArguments(arguments, Boolean.class);
+      boolean shouldCompileDependencies;
+      boolean generateDocs;
+      switch (arguments.length) {
+        case 2 -> {
+          var pair = Types.extractArguments(arguments, Boolean.class, Boolean.class);
+          shouldCompileDependencies = pair.getFirst();
+          generateDocs = pair.getSecond();
+        }
+        default -> {
+          shouldCompileDependencies = Types.extractArguments(arguments, Boolean.class);
+          generateDocs = false;
+        }
+      }
       try {
-        return context.getCompiler().compile(shouldCompileDependencies, useGlobalCache).get();
+        return context
+            .getCompiler()
+            .compile(shouldCompileDependencies, useGlobalCache, generateDocs)
+            .get();
       } catch (InterruptedException e) {
         throw new RuntimeException(e);
       } catch (ExecutionException e) {