ckdoc generate index.html plus several enhancements (spencer + ge)

Ge Wang committed 3 years ago

Commit ff084df1 parent cd9bf567 files · +217 −63Browse files

Unified · Split

7 files

src/core/chuck_type.cpp +0 −14
src/core/ulib_doc.cpp +144 −43
src/core/ulib_doc.h +6 −4
src/core/util_string.cpp +18 −0
src/core/util_string.h +2 −0
src/scripts/ckdoc/test-all.ck +22 −2
src/scripts/ckdoc/test-class.ck +25 −0

@@ -7132,20 +7132,6 @@ static bool comp_value( Chuck_Value * a, Chuck_Value * b ) · 7131 unmodified lines
7132	else return a->name > b->name;	7132	else return a->name > b->name;
7133	}	7133	}
7134		7134
7135	//-----------------------------------------------------------------------------
7136	// capitalize first character
7137	//-----------------------------------------------------------------------------
7138	static string capitalize( const string & s )
7139	{
7140	// copy
7141	string retval = s;
7142	// if not empty and first character is a lower-case letter
7143	if( retval.length() > 0 && retval[0] >= 'a' && retval[0] <= 'z' )
7144	retval[0] -= 32;
7145	// done
7146	return retval;
7147	}
7148
7149		7135
7150		7136
7151		7137

src/core/ulib_doc.cpp+144−43

 #include "util_string.h"
 #include <string>
+#include <sstream>
 #include <fstream>
 #include <algorithm>
 using namespace std;
     // outputToDir
     func = make_new_mfun( "int", "outputToDir", CKDoc_outputToDir );
     func->add_arg( "string", "path" );
-    func->doc = "Generate everything as files into the output directory";
+    func->add_arg( "string", "indexTitle" );
+    func->doc = "Generate everything as files into the output directory.";
     if( !type_engine_import_mfun( env, func ) ) goto error;
     // end the class import
-//-----------------------------------------------------------------------------
-// begin CKDoc implemention
-//-----------------------------------------------------------------------------
-std::string type2url( const std::string & type )
-{
-    return "[type2url NOT IMPLEMENTED]";
-}
 //-----------------------------------------------------------------------------
 // name: struct CKDocGroup | 1.5.0.0 (ge, spencer) added
 // desc: structure for a doc group e.g., "UGens"
+//-----------------------------------------------------------------------------
+// name: type2url()
+// desc: convert type name to URL, using groups to detemine the file for each
+//-----------------------------------------------------------------------------
+string type2url( const string & type, const vector<CKDocGroup *> & groups )
+{
+    // search
+    for( t_CKINT i = 0; i < groups.size(); i++ )
+    {
+        for( t_CKINT j = 0; j < groups[i]->types.size(); j++ )
+        {
+            // check
+            if( groups[i]->types[j] == NULL ) continue;
+            // compare
+            if( type == groups[i]->types[j]->name )
+            {
+                // file + location within file: basically: 'group.html#type'
+                return groups[i]->shortName + ".html#" + type;
+            }
+        }
+    }
+    // TODO: make a list of default classes on chuck website to link to
+    // return "[type2url NOT IMPLEMENTED]";
+    return "";
+}
 //-----------------------------------------------------------------------------
 // name: class CKDocHTMLOutput | 1.5.0.0 (ge, spencer) added
 // desc: HTML output (based on Spencer's ckdoc)
         // get the env
         m_env_ref = vm != NULL ? vm->env() : NULL;
     }
     // file extension
     virtual string fileExtension() const { return ".html"; }
+    // render HTML index
+    virtual string renderIndex( const string & indexTitle, const vector<CKDocGroup *> & groups );
 public:
-    void begin( const std::string & title )
+    void begin( const string & title )
     {
         // trim
         m_title = trim(title);
         m_outputStr += "</div>\n";
     }
-    void begin_classes()
+    void begin_classes( CKDocGroup * group )
     {
         m_outputStr += "<div class=\"classes\">\n";
+        m_outputStr += "<p class=\"group_desc\">" + group->desc + "</p>\n";
     }
     void end_classes()
         m_outputStr += "</div>\n";
     }
-    void begin_class(Chuck_Type * type)
+    void begin_class(Chuck_Type * type, const vector<CKDocGroup *> & groups )
     {
         m_outputStr += "<a name=\"" + type->name + "\" /><div class=\"class\">\n";
         m_outputStr += "<h2 class=\"class_title\" name=\"" + type->name + "\">" + type->name + "</h2>\n";
         // type heirarchy
         Chuck_Type * parent = type->parent;
         // check if there is a parent class
-        if( parent != NULL ) m_outputStr += "<h4 class=\"class_hierarchy\">";
+        if( parent != NULL )
+        {
+            m_outputStr += "<h4>";
+            m_outputStr += "<span class=\"class_inherits\">inherits</span> ";
+            // m_outputStr += "<h4 class=\"class_hierarchy\">";
+        }
         // iterate over parents
         while( parent != NULL )
         {
-            m_outputStr += ": <a href=\"" + type2url(parent->name)
+            m_outputStr += ": <a href=\"" + type2url(parent->name, groups)
                          + "\" class=\"" + css_class_for_type(m_env_ref, parent)
                          + "\">" + parent->name + "</a> ",
             // go up the inheritance chain
         if(type->doc.size() > 0)
         {
-            std::string doc;
+            std::string doc = capitalize(type->doc);
-            // if( m_doc_text_filter )
-            //     doc = m_doc_text_filter->filter(type->doc);
-            // else
-            doc = type->doc;
             m_outputStr += "<p class=\"class_description\">" + doc + "<p>\n";
         }
         else
         m_outputStr += "<span class=\"membername\">" + var->name + "</span></p>";
         if(var->doc.size() > 0)
-            m_outputStr += "<p class=\"member_description\">" + var->doc + "</p>\n";
+            m_outputStr += "<p class=\"member_description\">" + capitalize(var->doc) + "</p>\n";
         else
             m_outputStr += "<p class=\"empty_member_description\">No description available</p>\n";
             for(int i = 0; i < var->type->array_depth; i++)
                 m_outputStr += "[]";
         }
-        m_outputStr += "</span>";
+        m_outputStr += "</span> ";
         // function name
         m_outputStr += "<span class=\"membername\">" + var->name + "</span></p>";
         if(var->doc.size() > 0)
-            m_outputStr += "<p class=\"member_description\">" + var->doc + "</p>\n";
+            m_outputStr += "<p class=\"member_description\">" + capitalize(var->doc) + "</p>\n";
         else
             m_outputStr += "<p class=\"empty_member_description\">No description available</p>\n";
         m_outputStr += ")</p>\n";
         if(m_func->doc.size() > 0)
-            m_outputStr += "<p class=\"member_description\">" + m_func->doc + "</p>\n";
+            m_outputStr += "<p class=\"member_description\">" + capitalize(m_func->doc) + "</p>\n";
         else
             m_outputStr += "<p class=\"empty_member_description\">No description available</p>\n";
         m_outputStr += ")</p>\n";
         if(m_func->doc.size() > 0)
-            m_outputStr += "<p class=\"member_description\">" + m_func->doc + "</p>\n";
+            m_outputStr += "<p class=\"member_description\">" + capitalize(m_func->doc) + "</p>\n";
         else
             m_outputStr += "<p class=\"empty_member_description\">No description available</p>\n";
     static std::string css_class_for_type( Chuck_Env * env, Chuck_Type * type )
     {
         if( isprim(env, type) || isvoid(env, type) || (type->array_depth && isprim(env, type->array_type)) )
-            return "ckdoc_typename ckdoc_primitive_type";
+            return "ckdoc_typename ckdoc_type_primitive";
         else if(isugen(type))
-            return "ckdoc_typename ckdoc_ugen_type";
+            return "ckdoc_typename ckdoc_type_ugen";
         else
-            return "ckdoc_typename ckdoc_object_type";
+            return "ckdoc_typename ckdoc_type_object";
     }
 };
+//-----------------------------------------------------------------------------
+// name: renderIndex()
+// desc: render HTML index
+//-----------------------------------------------------------------------------
+string CKDocHTMLOutput::renderIndex( const string & title, const vector<CKDocGroup *> & groups )
+{
+    // output string stream
+    ostringstream sout;
+    // output index header
+    sout <<  "<html>\n<head>\n";
+    sout <<  "<title>" << title << "</title>\n";
+    sout <<  "<link rel=\"stylesheet\" type=\"text/css\" href=\"ckdoc.css\" />\n";
+    sout <<  "<link rel=\"stylesheet\" type=\"text/css\" href=\"class.css\" />\n";
+    sout <<  "</head>\n";
+    sout <<  "<body>\n";
+    sout <<  "<div id=\"title\">\n";
+    sout <<  "<div class=\"titleL\"><h1>" << title <<  "</h1></div>\n";
+    sout <<  "<div class=\"titleR\"><h1>&nbsp;</h1></div>\n";
+    sout <<  "</div>\n";
+    sout <<  "<div id=\"body\">\n";
+    // loop over groups
+    for( t_CKINT i = 0; i < groups.size(); i++ )
+    {
+        CKDocGroup * group = groups[i];
+        sout << "<div class=\"index_group\">\n";
+        sout << "<div class=\"index_group_title\">\n";
+        sout << "<h2><a href=\"" << group->shortName << ".html\">" << group->name << "</a></h2>\n";
+        sout << "<p class=\"index_group_desc\">" << group->desc << "</p>\n";
+        sout << "</div>\n";
+        sout << "<div class=\"index_group_classes\">\n";
+        sout << "<p>\n";
+        for( t_CKINT j = 0; j < group->types.size(); j++ )
+        {
+            Chuck_Type * type = group->types[j];
+            if( !type ) continue;
+            string cssClass = css_class_for_type( m_env_ref, type );
+            // TODO: check for array_depth
+            sout << "<a href=\"" << group->shortName << ".html#" << type->name << "\" class=\"" << cssClass << "\">" << type->name << "</a>\n";
+        }
+        sout << "</p>\n";
+        sout << "</div>\n";
+        sout << "<div class=\"clear\"></div>\n";
+        sout << "</div>\n";
+    }
+    sout << "</div>\n";
+    sout << "</body>\n</html>\n";
+    // return the string literal
+    return sout.str();
+};
 //-----------------------------------------------------------------------------
 // name: CKDoc()
 // desc: constructor
 // name: genIndex()
 // desc: generate top-level index file; return as string
 //-----------------------------------------------------------------------------
-string CKDoc::genIndex()
+string CKDoc::genIndex( const string & title )
 {
-    // return the string literal
+    // check
-    return "";
+    if( !m_output ) return "";
+    // generate index
+    return m_output->renderIndex( title, m_groups );
 }
     for( t_CKINT i = 0; i < m_groups.size(); i++ )
     {
         // generate each group
-        results[i] = genGroup( m_groups[i], FALSE );
+        results[i] = genGroup( m_groups[i], TRUE );
     }
 }
     }
     // begin type contents
-    output->begin_classes();
+    output->begin_classes( group );
     // iterate
     for( vector<Chuck_Type *>::const_iterator t = group->types.begin(); t != group->types.end(); t++ )
     if( clearOutput ) output->clear();
     // begin the type
-    output->begin_class( type );
+    output->begin_class( type, m_groups );
     // output examples
     if( type->examples.size() )
 // name: outputToDir()
 // desc: generate everything as files into the output directory
 //-----------------------------------------------------------------------------
-t_CKBOOL CKDoc::outputToDir( const string & outputDir )
+t_CKBOOL CKDoc::outputToDir( const string & outputDir, const string & indexTitle )
 {
     // groups content
     vector<string> groupOutput;
     m_output->clear();
     // gen index
-    if( !outputToFile( path + "index" + m_output->fileExtension(), genIndex() ) ) goto error;
+    if( !outputToFile( path + "index" + m_output->fileExtension(), genIndex( indexTitle ) ) ) goto error;
     // gen CSS
     if( !outputToFile( path + "ckdoc.css", genCSS() ) ) goto error;
     // gen groups
 {
     CKDoc * ckdoc = (CKDoc *)OBJ_MEMBER_UINT(SELF, CKDoc_offset_data);
     Chuck_String * path = GET_NEXT_STRING(ARGS);
+    Chuck_String * indexTitle = GET_NEXT_STRING(ARGS);
     // the path as c++ string
     string thePath;
+    string theTitle;
+    // check
+    theTitle = indexTitle != NULL ? indexTitle->str() : "";
     // check if null
     if( path == NULL ) {
     }
     // output
-    ckdoc->outputToDir( thePath );
+    ckdoc->outputToDir( thePath, theTitle );
 }
       margin-right: 0.5em;\n\
       line-height: 1.5em;\n\
   }\n\
+  .index_group_desc\n\
+  {\n\
+        color:#555;\n\
+  }\n\
+  \n\
+  .group_desc\n\
+  {\n\
+        color:#000;\n\
+  }\n\
 \n\
   .index_group_title a { color: black; }\n\
 \n\
       background-color: #eee;\n\
       padding: 0.25em 0.5em 1em 0.75em;\n\
       margin: 0;\n\
-      width: 6em;\n\
+      width: 9.5em;\n\
   }\n\
 \n\
   .toc_class\n\
   .classes\n\
   {\n\
       clear: right;\n\
-      margin-left: 9em;\n\
+      margin-left: 12em;\n\
       margin-right: 0em;\n\
   }\n\
 \n\
       font-family: Menlo, Monaco, Courier;\n\
       font-size: 18px;\n\
   }\n\
+  .class_inherits\n\
+  {\n\
+      font-weight: normal;\n\
+  }\n\
 \n\
   .class_hierarchy\n\
   {\n\
       font-family: Menlo, Monaco, Courier;\n\
       font-size: 14px;\n\
-      margin-right: 4em;\n\
+      /* margin-right: 4em; */ \n\
   }\n\
 \n\
   .class_section_header\n\

src/core/ulib_doc.h+6−4

     const std::string & str() const { return m_outputStr; }
     // get file name: ".html", ".txt", etc.
     virtual std::string fileExtension() const { return ""; }
+    // render index
+    virtual std::string renderIndex( const std::string & indexTitle, const std::vector<CKDocGroup *> & groups ) { return ""; };
 public:
     virtual void begin(const std::string &title) = 0;
     virtual void end_toc() = 0;
     // classes
-    virtual void begin_classes() = 0;
+    virtual void begin_classes( CKDocGroup * group ) = 0;
     virtual void end_classes() = 0;
     // one class
-    virtual void begin_class( Chuck_Type * type ) = 0;
+    virtual void begin_class( Chuck_Type * type, const std::vector<CKDocGroup *> & groups ) = 0;
     // examples
     virtual void begin_examples() = 0;
 public:
     // generate everything as files into the output directory
-    t_CKBOOL outputToDir( const std::string & outputDir );
+    t_CKBOOL outputToDir( const std::string & outputDir, const std::string & indexTitle );
     // generate top-level index file; return as string
-    std::string genIndex();
+    std::string genIndex( const std::string & title );
     // generate CSS; return as string
     std::string genCSS();
     // generate all added groups, return each in a separate entry

src/core/util_string.cpp+18−0

@@ -124,6 +124,24 @@ string toupper( const string & str ) · 123 unmodified lines
124		124
125		125
126		126
		127	//-----------------------------------------------------------------------------
		128	// name: capitalize()
		129	// capitalize first character
		130	//-----------------------------------------------------------------------------
		131	string capitalize( const string & s )
		132	{
		133	// copy
		134	string retval = s;
		135	// if not empty and first character is a lower-case letter
		136	if( retval.length() > 0 && retval[0] >= 'a' && retval[0] <= 'z' )
		137	retval[0] -= 32;
		138	// done
		139	return retval;
		140	}
		141
		142
		143
		144
127	//-----------------------------------------------------------------------------	145	//-----------------------------------------------------------------------------
128	// name: trim()	146	// name: trim()
129	// desc: ...	147	// desc: ...

src/core/util_string.h+2−0

@@ -53,6 +53,8 @@ std::string trim( const std::string & val ); · 52 unmodified lines
53	std::string ltrim( const std::string & val );	53	std::string ltrim( const std::string & val );
54	// rtrim	54	// rtrim
55	std::string rtrim( const std::string & val );	55	std::string rtrim( const std::string & val );
		56	// return capitalized copy of a string
		57	std::string capitalize( const std::string & s );
56		58
57	// argument extraction	59	// argument extraction
58	t_CKBOOL extract_args( const std::string & token,	60	t_CKBOOL extract_args( const std::string & token,

src/scripts/ckdoc/test-all.ck+22−2

@@ -15,7 +15,27 @@ Type.getTypes( · 14 unmodified lines
15	// instantiate	15	// instantiate
16	CKDoc doc; // documentation orchestra	16	CKDoc doc; // documentation orchestra
17		17
		18	// set the examples root
		19	"https://chuck.stanford.edu/doc/examples/" => doc.examplesRoot;
		20
		21	// add as group
		22	doc.addGroup( types, "Base Types (compiled in)", "base", "Base types in the ChucK" );
		23
		24	types.clear();
		25	// get types currently in ChucK type system
		26	Type.getTypes(
		27	types, // to be filled with results
		28	true, // include objects
		29	false, // include primitive types
		30	false, // include special types (@array and @function)
		31	false, // include builtin types
		32	true, // include types from chugins
		33	false, // include types from ck files in lib path
		34	false // include user-defined classes
		35	);
		36
18	// add as group	37	// add as group
19	doc.addGroup( types, "All", "all", "Here are some types in the ChucK VM" );	38	doc.addGroup( types, "Base Types (chugins)", "chugins", "ChucK Objects loaded from chugins" );
		39
20	// generate	40	// generate
21	doc.outputToDir( "." );	41	doc.outputToDir( ".", "ChucK Class Library Reference" );

src/scripts/ckdoc/test-class.ck+25−0

@@ -0,0 +1,25 @@
	1	public class Foo
	2	{
	3	/** a is an integer; nothing uses this. */
	4	int a;
	5	/** b is a float; nothing uses this either. */
	6	float b;
	7
	8	/** this function does nothing. */
	9	fun void bar( int x )
	10	{
	11	// \o/ this function does nothing" \o/
	12	// => this function does nothing" <=
	13	//=> this function does nothing
	14	/=> /
	15	}
	16	}
	17
	18	[ Foo.typeOf() ] @=> Type types[];
	19
	20	CKDoc doc;
	21
	22	doc.addGroup( types, "my classes!", "my", "Will this work?" );
	23
	24	// generate
	25	doc.outputToDir( ".", "My Class Library" );

ckdoc generate index.html plus several enhancements (spencer + ge)

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code