[tools:doc] Add Doc::RootDoc and support for .mystdoc.yml.

`.mystdoc.yml` is a file that specifies some metadata to include during documentation generation, including the name of the project, a version string, a homepage url, and a logo url. These can all be used by documentation renderers, then, to provide a more complete, customizable experience for individual projects.

.mystdoc.yml

@@ -0,0 +1,6 @@
+project_name: Myst
+version: v0.6.0
+homepage_url: https://myst-lang.org
+logo_url: https://avatars2.githubusercontent.com/u/29179527?s=200&v=4
+doc: |
+  Myst is a dynamic, general-purpose programming language.

src/myst/cli.cr

@@ -9,6 +9,7 @@ module Myst
       stop_evaluation = false
       generate_docs = false
       docs_directory = Dir.current
+      docs_yml = "./.mystdoc.yml"
 
       OptionParser.parse! do |opts|
         opts.banner = "Usage: myst [filename] [options]"
@@ -38,6 +39,10 @@ module Myst
           docs_directory = directory
         end
 
+        opts.on("--doc-yml DOC_YML", "Use the given file in place of ./.mystdoc.yml when generating metadata for documentation.") do |yml_file|
+          docs_yml = yml_file
+        end
+
         opts.on("-e", "--eval", "Eval code from args") do
           eval = true
         end
@@ -58,7 +63,7 @@ module Myst
 
 
       if generate_docs
-        Doc::Generator.auto_document(docs_directory)
+        Doc::Generator.auto_document(docs_directory, docs_yml)
         exit
       end
 

src/myst/tools/doc.cr

@@ -4,7 +4,7 @@ require "./doc/*"
 
 module Myst
   module Doc
-    alias DocContext = ModuleDoc | TypeDoc
+    alias DocContext = ModuleDoc | TypeDoc | RootDoc
 
     # An AST visitor for parsing doc comments from Myst source code and emitting
     # the content in a JSON structure.
@@ -14,8 +14,8 @@ module Myst
     class Generator
       # Automatically scan everything in the current directory to find Myst files
       # that can be documented.
-      def self.auto_document(directory = Dir.current)
-        generator = self.new
+      def self.auto_document(directory, doc_yml)
+        generator = self.new(doc_yml)
         Dir[directory, directory+"/**", directory+"/**/*"].uniq.each do |entry|
           # Only consider files that end with the `.mt` extension
           if entry.ends_with?(".mt")
@@ -30,8 +30,14 @@ module Myst
 
       @current_context : DocContext
 
-      def initialize
-        @docs = ModuleDoc.new("Root", "Root", nil)
+      def initialize(doc_yml : String)
+        @docs =
+          if File.exists?(doc_yml)
+            RootDoc.from_yaml(File.read(doc_yml))
+          else
+            RootDoc.new
+          end
+
         @current_context = @docs
       end
 
@@ -74,7 +80,7 @@ module Myst
       def visit(node : Def, doc : String?=nil)
         container =
           case context = @current_context
-          when ModuleDoc
+          when ModuleDoc, RootDoc
             context.methods
           when TypeDoc
             case
@@ -133,7 +139,12 @@ module Myst
       end
 
       private def make_full_path(basename : String) : String
-        @current_context.full_name + "." + basename
+        case context = @current_context
+        when RootDoc
+          basename
+        else
+          context.full_name + "." + basename
+        end
       end
     end
   end

src/myst/tools/doc/kind.cr

@@ -1,6 +1,7 @@
 module Myst
   module Doc
     enum Kind
+      ROOT
       CONSTANT
       METHOD
       MODULE

src/myst/tools/doc/root_doc.cr

@@ -0,0 +1,51 @@
+require "yaml"
+
+module Myst
+  module Doc
+    class RootDoc
+      property kind = Kind::ROOT
+      # These properties are meta information about the project being
+      # documented. These are pulled from the `.mystdoc.yml` file in the
+      # project's directory if one exists. Otherwise, they are mostly left nil.
+      property project_name : String? = nil
+      property version : String? = nil
+      property homepage_url : String? = nil
+      property logo_url : String? = nil
+      property doc : String? = nil
+
+
+      # These properties essentially mirror ModuleDoc and are generated by
+      # the tool's scan of Myst source files.
+      property submodules = {} of String => ModuleDoc
+      property subtypes = {} of String => TypeDoc
+      property constants = {} of String => ConstDoc
+      property methods = {} of String => MethodDoc
+
+
+      JSON.mapping(
+        kind: Kind,
+        project_name: {type: String?, emit_null: true},
+        version: {type: String?, emit_null: true},
+        homepage_url: {type: String?, emit_null: true},
+        logo_url: {type: String?, emit_null: true},
+        doc: {type: String?, emit_null: true},
+        submodules: Hash(String, ModuleDoc),
+        subtypes: Hash(String, TypeDoc),
+        constants: Hash(String, ConstDoc),
+        methods: Hash(String, MethodDoc)
+      )
+
+      YAML.mapping(
+        project_name: String?,
+        version: String?,
+        homepage_url: String?,
+        logo_url: String?,
+        doc: String?
+      )
+
+
+      def initialize
+      end
+    end
+  end
+end

stdlib/file.mt

@@ -1,5 +1,6 @@
 # File extends IO.FileDescriptor, but is initialized in the native library,
 # so the extension is not repeated here.
+
 deftype File
   #doc open(path : String, mode : String) -> file
   #| Creates a new File object for the file specified by `path` and opens it