History

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

Ge Wang committed 3 years ago

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

Showing the changes to src/core/ulib_doc.cpp (1 of 7 files). Show all

Unified · Split

src/core/ulib_doc.cpp+144−43
@@ -39,6 +39,7 @@ · 38 unmodified lines
3939 #include "util_string.h"
4040
4141 #include <string>
42+#include <sstream>
4243 #include <fstream>
4344 #include <algorithm>
4445 using namespace std;
@@ -192,7 +193,8 @@ DLL_QUERY ckdoc_query( Chuck_DL_Query * QUERY ) · 147 unmodified lines
192193 // outputToDir
193194 func = make_new_mfun( "int", "outputToDir", CKDoc_outputToDir );
194195 func->add_arg( "string", "path" );
195− func->doc = "Generate everything as files into the output directory";
196+ func->add_arg( "string", "indexTitle" );
197+ func->doc = "Generate everything as files into the output directory.";
196198 if( !type_engine_import_mfun( env, func ) ) goto error;
197199
198200 // end the class import
@@ -208,17 +210,6 @@ error: · 9 unmodified lines
208210
209211
210212
211−//-----------------------------------------------------------------------------
212−// begin CKDoc implemention
213−//-----------------------------------------------------------------------------
214−std::string type2url( const std::string & type )
215−{
216− return "[type2url NOT IMPLEMENTED]";
217−}
218−
219−
220−
221−
222213 //-----------------------------------------------------------------------------
223214 // name: struct CKDocGroup | 1.5.0.0 (ge, spencer) added
224215 // desc: structure for a doc group e.g., "UGens"
@@ -238,6 +229,37 @@ struct CKDocGroup · 13 unmodified lines
238229
239230
240231
232+//-----------------------------------------------------------------------------
233+// name: type2url()
234+// desc: convert type name to URL, using groups to detemine the file for each
235+//-----------------------------------------------------------------------------
236+string type2url( const string & type, const vector<CKDocGroup *> & groups )
237+{
238+ // search
239+ for( t_CKINT i = 0; i < groups.size(); i++ )
240+ {
241+ for( t_CKINT j = 0; j < groups[i]->types.size(); j++ )
242+ {
243+ // check
244+ if( groups[i]->types[j] == NULL ) continue;
245+ // compare
246+ if( type == groups[i]->types[j]->name )
247+ {
248+ // file + location within file: basically: 'group.html#type'
249+ return groups[i]->shortName + ".html#" + type;
250+ }
251+ }
252+ }
253+
254+ // TODO: make a list of default classes on chuck website to link to
255+ // return "[type2url NOT IMPLEMENTED]";
256+ return "";
257+}
258+
259+
260+
261+
262+
241263 //-----------------------------------------------------------------------------
242264 // name: class CKDocHTMLOutput | 1.5.0.0 (ge, spencer) added
243265 // desc: HTML output (based on Spencer's ckdoc)
@@ -257,12 +279,13 @@ public: · 13 unmodified lines
257279 // get the env
258280 m_env_ref = vm != NULL ? vm->env() : NULL;
259281 }
260−
261282 // file extension
262283 virtual string fileExtension() const { return ".html"; }
284+ // render HTML index
285+ virtual string renderIndex( const string & indexTitle, const vector<CKDocGroup *> & groups );
263286
264287 public:
265− void begin( const std::string & title )
288+ void begin( const string & title )
266289 {
267290 // trim
268291 m_title = trim(title);
@@ -323,9 +346,10 @@ public: · 54 unmodified lines
323346 m_outputStr += "</div>\n";
324347 }
325348
326− void begin_classes()
349+ void begin_classes( CKDocGroup * group )
327350 {
328351 m_outputStr += "<div class=\"classes\">\n";
352+ m_outputStr += "<p class=\"group_desc\">" + group->desc + "</p>\n";
329353 }
330354
331355 void end_classes()
@@ -333,7 +357,7 @@ public: · 1 unmodified line
333357 m_outputStr += "</div>\n";
334358 }
335359
336− void begin_class(Chuck_Type * type)
360+ void begin_class(Chuck_Type * type, const vector<CKDocGroup *> & groups )
337361 {
338362 m_outputStr += "<a name=\"" + type->name + "\" /><div class=\"class\">\n";
339363 m_outputStr += "<h2 class=\"class_title\" name=\"" + type->name + "\">" + type->name + "</h2>\n";
@@ -341,11 +365,16 @@ public: · 1 unmodified line
341365 // type heirarchy
342366 Chuck_Type * parent = type->parent;
343367 // check if there is a parent class
344− if( parent != NULL ) m_outputStr += "<h4 class=\"class_hierarchy\">";
368+ if( parent != NULL )
369+ {
370+ m_outputStr += "<h4>";
371+ m_outputStr += "<span class=\"class_inherits\">inherits</span> ";
372+ // m_outputStr += "<h4 class=\"class_hierarchy\">";
373+ }
345374 // iterate over parents
346375 while( parent != NULL )
347376 {
348− m_outputStr += ": <a href=\"" + type2url(parent->name)
377+ m_outputStr += ": <a href=\"" + type2url(parent->name, groups)
349378 + "\" class=\"" + css_class_for_type(m_env_ref, parent)
350379 + "\">" + parent->name + "</a> ",
351380 // go up the inheritance chain
@@ -356,11 +385,7 @@ public: · 4 unmodified lines
356385
357386 if(type->doc.size() > 0)
358387 {
359− std::string doc;
360− // if( m_doc_text_filter )
361− // doc = m_doc_text_filter->filter(type->doc);
362− // else
363− doc = type->doc;
388+ std::string doc = capitalize(type->doc);
364389 m_outputStr += "<p class=\"class_description\">" + doc + "<p>\n";
365390 }
366391 else
@@ -447,7 +472,7 @@ public: · 80 unmodified lines
447472 m_outputStr += "<span class=\"membername\">" + var->name + "</span></p>";
448473
449474 if(var->doc.size() > 0)
450− m_outputStr += "<p class=\"member_description\">" + var->doc + "</p>\n";
475+ m_outputStr += "<p class=\"member_description\">" + capitalize(var->doc) + "</p>\n";
451476 else
452477 m_outputStr += "<p class=\"empty_member_description\">No description available</p>\n";
453478
@@ -466,13 +491,13 @@ public: · 12 unmodified lines
466491 for(int i = 0; i < var->type->array_depth; i++)
467492 m_outputStr += "[]";
468493 }
469− m_outputStr += "</span>";
494+ m_outputStr += "</span> ";
470495
471496 // function name
472497 m_outputStr += "<span class=\"membername\">" + var->name + "</span></p>";
473498
474499 if(var->doc.size() > 0)
475− m_outputStr += "<p class=\"member_description\">" + var->doc + "</p>\n";
500+ m_outputStr += "<p class=\"member_description\">" + capitalize(var->doc) + "</p>\n";
476501 else
477502 m_outputStr += "<p class=\"empty_member_description\">No description available</p>\n";
478503
@@ -506,7 +531,7 @@ public: · 27 unmodified lines
506531 m_outputStr += ")</p>\n";
507532
508533 if(m_func->doc.size() > 0)
509− m_outputStr += "<p class=\"member_description\">" + m_func->doc + "</p>\n";
534+ m_outputStr += "<p class=\"member_description\">" + capitalize(m_func->doc) + "</p>\n";
510535 else
511536 m_outputStr += "<p class=\"empty_member_description\">No description available</p>\n";
512537
@@ -542,7 +567,7 @@ public: · 29 unmodified lines
542567 m_outputStr += ")</p>\n";
543568
544569 if(m_func->doc.size() > 0)
545− m_outputStr += "<p class=\"member_description\">" + m_func->doc + "</p>\n";
570+ m_outputStr += "<p class=\"member_description\">" + capitalize(m_func->doc) + "</p>\n";
546571 else
547572 m_outputStr += "<p class=\"empty_member_description\">No description available</p>\n";
548573
@@ -596,17 +621,73 @@ public: · 47 unmodified lines
596621 static std::string css_class_for_type( Chuck_Env * env, Chuck_Type * type )
597622 {
598623 if( isprim(env, type) || isvoid(env, type) || (type->array_depth && isprim(env, type->array_type)) )
599− return "ckdoc_typename ckdoc_primitive_type";
624+ return "ckdoc_typename ckdoc_type_primitive";
600625 else if(isugen(type))
601− return "ckdoc_typename ckdoc_ugen_type";
626+ return "ckdoc_typename ckdoc_type_ugen";
602627 else
603− return "ckdoc_typename ckdoc_object_type";
628+ return "ckdoc_typename ckdoc_type_object";
604629 }
605630 };
606631
607632
608633
609634
635+//-----------------------------------------------------------------------------
636+// name: renderIndex()
637+// desc: render HTML index
638+//-----------------------------------------------------------------------------
639+string CKDocHTMLOutput::renderIndex( const string & title, const vector<CKDocGroup *> & groups )
640+{
641+ // output string stream
642+ ostringstream sout;
643+
644+ // output index header
645+ sout << "<html>\n<head>\n";
646+ sout << "<title>" << title << "</title>\n";
647+ sout << "<link rel=\"stylesheet\" type=\"text/css\" href=\"ckdoc.css\" />\n";
648+ sout << "<link rel=\"stylesheet\" type=\"text/css\" href=\"class.css\" />\n";
649+ sout << "</head>\n";
650+ sout << "<body>\n";
651+ sout << "<div id=\"title\">\n";
652+ sout << "<div class=\"titleL\"><h1>" << title << "</h1></div>\n";
653+ sout << "<div class=\"titleR\"><h1>&nbsp;</h1></div>\n";
654+ sout << "</div>\n";
655+ sout << "<div id=\"body\">\n";
656+
657+ // loop over groups
658+ for( t_CKINT i = 0; i < groups.size(); i++ )
659+ {
660+ CKDocGroup * group = groups[i];
661+ sout << "<div class=\"index_group\">\n";
662+ sout << "<div class=\"index_group_title\">\n";
663+ sout << "<h2><a href=\"" << group->shortName << ".html\">" << group->name << "</a></h2>\n";
664+ sout << "<p class=\"index_group_desc\">" << group->desc << "</p>\n";
665+ sout << "</div>\n";
666+ sout << "<div class=\"index_group_classes\">\n";
667+ sout << "<p>\n";
668+
669+ for( t_CKINT j = 0; j < group->types.size(); j++ )
670+ {
671+ Chuck_Type * type = group->types[j];
672+ if( !type ) continue;
673+ string cssClass = css_class_for_type( m_env_ref, type );
674+ // TODO: check for array_depth
675+ sout << "<a href=\"" << group->shortName << ".html#" << type->name << "\" class=\"" << cssClass << "\">" << type->name << "</a>\n";
676+ }
677+ sout << "</p>\n";
678+ sout << "</div>\n";
679+ sout << "<div class=\"clear\"></div>\n";
680+ sout << "</div>\n";
681+ }
682+ sout << "</div>\n";
683+ sout << "</body>\n</html>\n";
684+
685+ // return the string literal
686+ return sout.str();
687+};
688+
689+
690+
610691 //-----------------------------------------------------------------------------
611692 // name: CKDoc()
612693 // desc: constructor
@@ -848,10 +929,12 @@ string CKDoc::getExamplesRoot() const · 235 unmodified lines
848929 // name: genIndex()
849930 // desc: generate top-level index file; return as string
850931 //-----------------------------------------------------------------------------
851−string CKDoc::genIndex()
932+string CKDoc::genIndex( const string & title )
852933 {
853− // return the string literal
854− return "";
934+ // check
935+ if( !m_output ) return "";
936+ // generate index
937+ return m_output->renderIndex( title, m_groups );
855938 }
856939
857940
@@ -896,7 +979,7 @@ void CKDoc::genGroups( vector<string> & results ) · 38 unmodified lines
896979 for( t_CKINT i = 0; i < m_groups.size(); i++ )
897980 {
898981 // generate each group
899− results[i] = genGroup( m_groups[i], FALSE );
982+ results[i] = genGroup( m_groups[i], TRUE );
900983 }
901984 }
902985
@@ -951,7 +1034,7 @@ string CKDoc::genGroup( CKDocGroup * group, t_CKBOOL clearOutput ) · 48 unmodified lines
9511034 }
9521035
9531036 // begin type contents
954− output->begin_classes();
1037+ output->begin_classes( group );
9551038
9561039 // iterate
9571040 for( vector<Chuck_Type *>::const_iterator t = group->types.begin(); t != group->types.end(); t++ )
@@ -991,7 +1074,7 @@ string CKDoc::genType( Chuck_Type * type, t_CKBOOL clearOutput ) · 33 unmodified lines
9911074 if( clearOutput ) output->clear();
9921075
9931076 // begin the type
994− output->begin_class( type );
1077+ output->begin_class( type, m_groups );
9951078
9961079 // output examples
9971080 if( type->examples.size() )
@@ -1190,7 +1273,7 @@ string CKDoc::genType( Chuck_Type * type, t_CKBOOL clearOutput ) · 192 unmodified lines
11901273 // name: outputToDir()
11911274 // desc: generate everything as files into the output directory
11921275 //-----------------------------------------------------------------------------
1193−t_CKBOOL CKDoc::outputToDir( const string & outputDir )
1276+t_CKBOOL CKDoc::outputToDir( const string & outputDir, const string & indexTitle )
11941277 {
11951278 // groups content
11961279 vector<string> groupOutput;
@@ -1204,7 +1287,7 @@ t_CKBOOL CKDoc::outputToDir( const string & outputDir ) · 7 unmodified lines
12041287 m_output->clear();
12051288
12061289 // gen index
1207− if( !outputToFile( path + "index" + m_output->fileExtension(), genIndex() ) ) goto error;
1290+ if( !outputToFile( path + "index" + m_output->fileExtension(), genIndex( indexTitle ) ) ) goto error;
12081291 // gen CSS
12091292 if( !outputToFile( path + "ckdoc.css", genCSS() ) ) goto error;
12101293 // gen groups
@@ -1503,8 +1586,13 @@ CK_DLL_MFUN( CKDoc_outputToDir ) · 292 unmodified lines
15031586 {
15041587 CKDoc * ckdoc = (CKDoc *)OBJ_MEMBER_UINT(SELF, CKDoc_offset_data);
15051588 Chuck_String * path = GET_NEXT_STRING(ARGS);
1589+ Chuck_String * indexTitle = GET_NEXT_STRING(ARGS);
15061590 // the path as c++ string
15071591 string thePath;
1592+ string theTitle;
1593+
1594+ // check
1595+ theTitle = indexTitle != NULL ? indexTitle->str() : "";
15081596
15091597 // check if null
15101598 if( path == NULL ) {
@@ -1515,7 +1603,7 @@ CK_DLL_MFUN( CKDoc_outputToDir ) · 4 unmodified lines
15151603 }
15161604
15171605 // output
1518− ckdoc->outputToDir( thePath );
1606+ ckdoc->outputToDir( thePath, theTitle );
15191607 }
15201608
15211609
@@ -1564,6 +1652,15 @@ string CKDoc::m_ckdocCSS = "\ · 42 unmodified lines
15641652 margin-right: 0.5em;\n\
15651653 line-height: 1.5em;\n\
15661654 }\n\
1655+ .index_group_desc\n\
1656+ {\n\
1657+ color:#555;\n\
1658+ }\n\
1659+ \n\
1660+ .group_desc\n\
1661+ {\n\
1662+ color:#000;\n\
1663+ }\n\
15671664 \n\
15681665 .index_group_title a { color: black; }\n\
15691666 \n\
@@ -1612,7 +1709,7 @@ string CKDoc::m_ckdocCSS = "\ · 42 unmodified lines
16121709 background-color: #eee;\n\
16131710 padding: 0.25em 0.5em 1em 0.75em;\n\
16141711 margin: 0;\n\
1615− width: 6em;\n\
1712+ width: 9.5em;\n\
16161713 }\n\
16171714 \n\
16181715 .toc_class\n\
@@ -1625,7 +1722,7 @@ string CKDoc::m_ckdocCSS = "\ · 6 unmodified lines
16251722 .classes\n\
16261723 {\n\
16271724 clear: right;\n\
1628− margin-left: 9em;\n\
1725+ margin-left: 12em;\n\
16291726 margin-right: 0em;\n\
16301727 }\n\
16311728 \n\
@@ -1640,12 +1737,16 @@ string CKDoc::m_ckdocCSS = "\ · 8 unmodified lines
16401737 font-family: Menlo, Monaco, Courier;\n\
16411738 font-size: 18px;\n\
16421739 }\n\
1740+ .class_inherits\n\
1741+ {\n\
1742+ font-weight: normal;\n\
1743+ }\n\
16431744 \n\
16441745 .class_hierarchy\n\
16451746 {\n\
16461747 font-family: Menlo, Monaco, Courier;\n\
16471748 font-size: 14px;\n\
1648− margin-right: 4em;\n\
1749+ /* margin-right: 4em; */ \n\
16491750 }\n\
16501751 \n\
16511752 .class_section_header\n\

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t