History

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
  1. src/core/chuck_type.cpp +0 −14
  2. src/core/ulib_doc.cpp +144 −43
  3. src/core/ulib_doc.h +6 −4
  4. src/core/util_string.cpp +18 −0
  5. src/core/util_string.h +2 −0
  6. src/scripts/ckdoc/test-all.ck +22 −2
  7. src/scripts/ckdoc/test-class.ck +25 −0
src/core/chuck_type.cpp+0−14
@@ -7132,20 +7132,6 @@ static bool comp_value( Chuck_Value * a, Chuck_Value * b ) · 7131 unmodified lines
71327132 else return a->name > b->name;
71337133 }
71347134
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−
71497135
71507136
71517137
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\
src/core/ulib_doc.h+6−4
@@ -69,6 +69,8 @@ public: · 68 unmodified lines
6969 const std::string & str() const { return m_outputStr; }
7070 // get file name: ".html", ".txt", etc.
7171 virtual std::string fileExtension() const { return ""; }
72+ // render index
73+ virtual std::string renderIndex( const std::string & indexTitle, const std::vector<CKDocGroup *> & groups ) { return ""; };
7274
7375 public:
7476 virtual void begin(const std::string &title) = 0;
@@ -85,11 +87,11 @@ public: · 10 unmodified lines
8587 virtual void end_toc() = 0;
8688
8789 // classes
88− virtual void begin_classes() = 0;
90+ virtual void begin_classes( CKDocGroup * group ) = 0;
8991 virtual void end_classes() = 0;
9092
9193 // one class
92− virtual void begin_class( Chuck_Type * type ) = 0;
94+ virtual void begin_class( Chuck_Type * type, const std::vector<CKDocGroup *> & groups ) = 0;
9395
9496 // examples
9597 virtual void begin_examples() = 0;
@@ -167,9 +169,9 @@ public: · 71 unmodified lines
167169
168170 public:
169171 // generate everything as files into the output directory
170− t_CKBOOL outputToDir( const std::string & outputDir );
172+ t_CKBOOL outputToDir( const std::string & outputDir, const std::string & indexTitle );
171173 // generate top-level index file; return as string
172− std::string genIndex();
174+ std::string genIndex( const std::string & title );
173175 // generate CSS; return as string
174176 std::string genCSS();
175177 // 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
124124
125125
126126
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+
127145 //-----------------------------------------------------------------------------
128146 // name: trim()
129147 // desc: ...
src/core/util_string.h+2−0
@@ -53,6 +53,8 @@ std::string trim( const std::string & val ); · 52 unmodified lines
5353 std::string ltrim( const std::string & val );
5454 // rtrim
5555 std::string rtrim( const std::string & val );
56+// return capitalized copy of a string
57+std::string capitalize( const std::string & s );
5658
5759 // argument extraction
5860 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
1515 // instantiate
1616 CKDoc doc; // documentation orchestra
1717
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+
1837 // 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+
2040 // 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" );

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