From c42a9faad8d84f7bd05457d5f8e1fe45d6eecfa2 Mon Sep 17 00:00:00 2001
From: Yong He <yonghe@outlook.com>
Date: Tue, 8 Oct 2024 13:29:57 -0700
Subject: Overhaul docgen tool and setup CI to generate stdlib reference.
 (#5232)

* Overhaul docgen tool and setup CI to generate stdlib reference.

* Fix build error.

* Write parsed doc for all decls.

* fix.

* fix callout.

* Fix.

* Fix comment.

* Fix.

* Delete obsolete doc tests.

* Fix.

* Categorize functions and types.

* Fix CI.

* Update comments.
---
 source/slang/slang.cpp | 91 +++++++++++++++++++++-----------------------------
 1 file changed, 38 insertions(+), 53 deletions(-)

(limited to 'source/slang/slang.cpp')

diff --git a/source/slang/slang.cpp b/source/slang/slang.cpp
index 5fcf20e0a..4bdbbd0aa 100644
--- a/source/slang/slang.cpp
+++ b/source/slang/slang.cpp
@@ -312,8 +312,39 @@ SlangResult Session::checkPassThroughSupport(SlangPassThrough inPassThrough)
     return checkExternalCompilerSupport(this, PassThroughMode(inPassThrough));
 }
 
+void Session::writeStdlibDoc(String config)
+{
+    ASTBuilder* astBuilder = getBuiltinLinkage()->getASTBuilder();
+    SourceManager* sourceManager = getBuiltinSourceManager();
+
+    DiagnosticSink sink(sourceManager, Lexer::sourceLocationLexer);
+
+    List<String> docStrings;
+
+    // For all the modules add their doc output to docStrings
+    for (Module* stdlibModule : stdlibModules)
+    {
+        RefPtr<ASTMarkup> markup(new ASTMarkup);
+        ASTMarkupUtil::extract(stdlibModule->getModuleDecl(), sourceManager, &sink, markup);
+
+        DocMarkdownWriter writer(markup, astBuilder, &sink);
+        auto rootPage = writer.writeAll(config.getUnownedSlice());
+        File::writeAllText("toc.html", writer.writeTOC());
+        rootPage->writeToDisk();
+    }
+    ComPtr<ISlangBlob> diagnosticBlob;
+    sink.getBlobIfNeeded(diagnosticBlob.writeRef());
+    if (diagnosticBlob && diagnosticBlob->getBufferSize() != 0)
+    {
+        // Write the diagnostic blob to stdout.
+        fprintf(stderr, "%s", (const char*)diagnosticBlob->getBufferPointer());
+    }
+}
+
 SlangResult Session::compileStdLib(slang::CompileStdLibFlags compileFlags)
 {
+    SLANG_AST_BUILDER_RAII(m_builtinLinkage->getASTBuilder());
+
     if (m_builtinLinkage->mapNameToLoadedModules.getCount())
     {
         // Already have a StdLib loaded
@@ -339,40 +370,15 @@ SlangResult Session::compileStdLib(slang::CompileStdLibFlags compileFlags)
 
     if (compileFlags & slang::CompileStdLibFlag::WriteDocumentation)
     {
-        // Not 100% clear where best to get the ASTBuilder from, but from the linkage shouldn't
-        // cause any problems with scoping
-
-        ASTBuilder* astBuilder = getBuiltinLinkage()->getASTBuilder();
-        SourceManager* sourceManager = getBuiltinSourceManager();
-
-        DiagnosticSink sink(sourceManager, Lexer::sourceLocationLexer);
-
-        List<String> docStrings;
-
-        // For all the modules add their doc output to docStrings
-        for (Module* stdlibModule : stdlibModules)
+        // Load config file first.
+        String configText;
+        if (SLANG_FAILED(File::readAllText("config.txt", configText)))
         {
-            RefPtr<ASTMarkup> markup(new ASTMarkup);
-            ASTMarkupUtil::extract(stdlibModule->getModuleDecl(), sourceManager, &sink, markup);
-
-            DocMarkdownWriter writer(markup, astBuilder);
-            writer.writeAll();
-            docStrings.add(writer.getOutput());
+            fprintf(stderr, "Error writing documentation: config file not found on current working directory.\n");
         }
-
-        // Combine all together in stdlib-doc.md output fiel
+        else
         {
-            String fileName("stdlib-doc.md");
-
-            RefPtr<FileStream> stream = new FileStream;
-            SLANG_RETURN_ON_FAIL(stream->init(fileName, FileMode::Create));
-            StreamWriter writer;
-            SLANG_RETURN_ON_FAIL(writer.init(stream));
-
-            for (auto& docString : docStrings)
-            {
-                SLANG_RETURN_ON_FAIL(writer.write(docString));
-            }
+            writeStdlibDoc(configText);
         }
     }
 
@@ -3161,28 +3167,7 @@ SlangResult FrontEndCompileRequest::executeActionsInner()
     // After semantic checking is performed we can try and output doc information for this
     if (optionSet.getBoolOption(CompilerOptionName::Doc))
     {
-        // Not 100% clear where best to get the ASTBuilder from, but from the linkage shouldn't
-        // cause any problems with scoping
-        ASTBuilder* astBuilder = getLinkage()->getASTBuilder();
-
-        ISlangWriter* writer = getSink()->writer;
-
-        // Write output to the diagnostic writer
-        if (writer)
-        {
-            for (TranslationUnitRequest* translationUnit : translationUnits)
-            {
-                RefPtr<ASTMarkup> markup(new ASTMarkup);
-                ASTMarkupUtil::extract(translationUnit->getModuleDecl(), getSourceManager(), getSink(), markup);
-
-                // Convert to markdown
-                DocMarkdownWriter markdownWriter(markup, astBuilder);
-                markdownWriter.writeAll();
-
-                UnownedStringSlice docText = markdownWriter.getOutput().getUnownedSlice();
-                writer->write(docText.begin(), docText.getLength());
-            }
-        }
+        // TODO: implement the logic to output generated documents to target directory/zip file.
     }
 
     // Look up all the entry points that are expected,
-- 
cgit v1.2.3