diff --git a/src/core/ulib_doc.cpp b/src/core/ulib_doc.cpp index 857dab044..6d41d93f0 100644 --- a/src/core/ulib_doc.cpp +++ b/src/core/ulib_doc.cpp @@ -49,6 +49,7 @@ CK_DLL_CTOR( CKDoc_ctor ); CK_DLL_DTOR( CKDoc_dtor ); CK_DLL_MFUN( CKDoc_addGroup_str ); CK_DLL_MFUN( CKDoc_addGroup_type ); +CK_DLL_MFUN( CKDoc_addGroup_ext ); CK_DLL_MFUN( CKDoc_numGroups ); CK_DLL_MFUN( CKDoc_clearGroup ); CK_DLL_CTRL( CKDoc_examplesRoot_set ); @@ -130,6 +131,15 @@ DLL_QUERY ckdoc_query( Chuck_DL_Query * QUERY ) func->doc = "Add a group of types (by type name) to be documented, including group 'name', a 'shortName' to be used for any files, and a group 'description'."; if( !type_engine_import_mfun( env, func ) ) goto error; + // addGroupExternal | 1.5.2.4 (ge) added + func = make_new_mfun( "void", "addGroupExternal", CKDoc_addGroup_ext ); + func->add_arg( "string", "name" ); + func->add_arg( "string", "URL" ); + func->add_arg( "string", "description" ); + func->add_arg( "string", "longDesc" ); + func->doc = "Add a group documention at an external URL location"; + if( !type_engine_import_mfun( env, func ) ) goto error; + // numGroups func = make_new_mfun( "int", "numGroups", CKDoc_numGroups ); func->doc = "Get the number of groups added."; @@ -225,6 +235,8 @@ struct CKDocGroup string shortName; // description of the group string desc; + // long description (for groups that point to external CKDoc) | 1.5.2.4 (ge) added + string longDesc; }; @@ -737,22 +749,43 @@ string CKDocHTMLOutput::renderIndex( const string & title, const vectortypes.size() != 0; + sout << "
\n"; sout << "
\n"; - sout << "

shortName << ".html\">" << group->name << "

\n"; + + // group name, either linking to generate page (Type A) to external page (Type B) + // 1.5.2.4 (ge, azaday) add type B support + if( typeA ) sout << "

shortName << ".html\">"; + else sout << "

shortName << "\">"; + sout << group->name << "

\n"; + sout << "

" << group->desc << "

\n"; sout << "

\n"; - sout << "
\n"; - sout << "

\n"; - for( t_CKINT j = 0; j < group->types.size(); j++ ) + // type A == normal + if( typeA ) { - 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 << "shortName << ".html#" << type->base_name << "\" class=\"" << cssClass << "\">" << type->base_name << "\n"; + sout << "

\n"; + sout << "

\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 << "shortName << ".html#" << type->base_name << "\" class=\"" << cssClass << "\">" << type->base_name << "\n"; + } } + else // type B | 1.5.2.4 (ge, azaday) added + { + sout << "

\n"; + sout << "

\n"; + sout << group->longDesc << "\n"; + } + sout << "

\n"; sout << "
\n"; sout << "
\n"; @@ -901,6 +934,36 @@ t_CKBOOL CKDoc::addGroup( const vector & types, const string & nam +//----------------------------------------------------------------------------- +// name: addGroupExt() | 1.5.2.4 (ge) added +// desc: add an external group to document +//----------------------------------------------------------------------------- +t_CKBOOL CKDoc::addGroupExt( const string & name, const string & URL, + const string & desc, const string & longDesc ) +{ + // allocate group + CKDocGroup * group = new CKDocGroup(); + // check + if( !group ) + { + EM_error3( "[CKDoc.addGroup()]: could not allocate new memory...bailing out" ); + return FALSE; + } + + // copy + group->name = trim(name); + group->shortName = trim(URL); + group->desc = trim(desc); + group->longDesc = trim(longDesc); + + // add to groups + m_groups.push_back( group ); + + return TRUE; +} + + + //----------------------------------------------------------------------------- // name: numGroups() // desc: get number of groups @@ -1431,8 +1494,13 @@ t_CKBOOL CKDoc::outputToDir( const string & outputDir, const string & indexTitle // for each group for( t_CKINT i = 0; i < m_groups.size(); i++ ) { - if( !outputToFile( path + m_groups[i]->shortName + m_output->fileExtension(), groupOutput[i] ) ) - goto error; + // check if Type A or Type B | 1.5.2.4 (ge) added check to distinguish group type + if( m_groups[i]->types.size() ) + { + // not external, output new file + if( !outputToFile( path + m_groups[i]->shortName + m_output->fileExtension(), groupOutput[i] ) ) + goto error; + } } // done @@ -1598,6 +1666,30 @@ CK_DLL_MFUN( CKDoc_addGroup_str ) RETURN->v_int = FALSE; } +CK_DLL_MFUN( CKDoc_addGroup_ext ) // 1.5.2.4 (ge) added +{ + CKDoc * ckdoc = (CKDoc *)OBJ_MEMBER_UINT(SELF, CKDoc_offset_data); + Chuck_String * groupName = GET_NEXT_STRING(ARGS); + Chuck_String * URL = GET_NEXT_STRING(ARGS); + Chuck_String * desc = GET_NEXT_STRING(ARGS); + Chuck_String * longDesc = GET_NEXT_STRING(ARGS); + + // add group + ckdoc->addGroupExt( groupName ? groupName->str() : "", + URL ? URL->str() : "", + desc ? desc->str() : "", + longDesc ? longDesc->str() : "" ); + + // set return value + RETURN->v_int = TRUE; + // done + return; + +error: + RETURN->v_int = FALSE; +} + + CK_DLL_MFUN( CKDoc_numGroups ) { CKDoc * ckdoc = (CKDoc *)OBJ_MEMBER_UINT(SELF, CKDoc_offset_data); @@ -1806,6 +1898,23 @@ a\n\ line-height: 1.5em;\n\ }\n\ \n\ +.index_group_external\n\ +{\n\ + padding-top: 0.15em;\n\ + padding-left: 1em;\n\ + padding-bottom: 0.15em;\n\ +\n\ + margin: 0;\n\ + margin-left: 20%;\n\ + width: 75%;\n\ +}\n\ +\n\ +.index_group_external a\n\ +{\n\ + margin-right: 0;\n\ + line-height: 1.5em;\n\ +}\n\ +\n\ .index_group_desc\n\ {\n\ color: #555;\n\ diff --git a/src/core/ulib_doc.h b/src/core/ulib_doc.h index 5d62d2182..04eab66d1 100644 --- a/src/core/ulib_doc.h +++ b/src/core/ulib_doc.h @@ -154,11 +154,16 @@ class CKDoc void clearGroups(); // clear output generator void clearOutput(); - // add a group of types to document + // add a group of types to document (Type A) t_CKBOOL addGroup( const std::vector & types, const std::string & name, const std::string & shortName, - const std::string & description ); + const std::string & description ); + // add an external group of types to document (Type B) | 1.5.2.4 (ge) added + t_CKBOOL addGroupExt( const std::string & name, + const std::string & URL, + const std::string & description, + const std::string & longDesc ); // get number of groups t_CKINT numGroups() const; // set output format: CKDoc.HTML, CKDoc.TEXT, CKDoc.MARKDOWN, CKDoc.JSON diff --git a/src/scripts/ckdoc/gen-all.ck b/src/scripts/ckdoc/gen-all.ck index 89480ae1c..0e74434ee 100644 --- a/src/scripts/ckdoc/gen-all.ck +++ b/src/scripts/ckdoc/gen-all.ck @@ -85,18 +85,17 @@ doc.addGroup( "Advanced and specialty unit generators" ); -// add group -doc.addGroup( - [ "ABSaturator", "AmbPan3", "Bitcrusher", "Elliptic", "ExpDelay", "ExpEnv", "FIR", - "FoldbackSaturator", "GVerb", "KasFilter", "MagicSine", "Mesh2D", "Multicomb", - "Pan4", "Pan8", "Pan16", "PitchTrack", "PowerADSR", "RegEx", "Sigmund", - "Spectacle", "WinFuncEnv", "WPDiodeLadder", "WPKorg35" ], + +// add group (external; i.e., API reference root elsewhere) +doc.addGroupExternal( // group name - "Chugins Library", - // file name - "chugins", - // group descriptions - "Default chugins library offering unit generators and utilities." + "ChuGL", + // URL + "../../chugl/api/", + // group description + "Strongly-timed 2D/3D graphics programming using Graphics Generators (GGens)", + // long text description + "ChuGL (sounds like \"chuckle\"; rhymes with \"juggle\") is a unified audiovisual programming framework in the ChucK programming language. It expands ChucK's strongly-timed, concurrent programming model and real-time audio synthesis capabilities with a hardware-accelerated 3D graphics engine and API. (See also: ChuGL homepage | ChuGL API Reference)" ); // add group @@ -148,6 +147,21 @@ doc.addGroup( "Additional Utiilities" ); + +// add group +doc.addGroup( + [ "ABSaturator", "AmbPan3", "Bitcrusher", "Elliptic", "ExpDelay", "ExpEnv", "FIR", + "FoldbackSaturator", "GVerb", "KasFilter", "MagicSine", "Mesh2D", "Multicomb", + "Pan4", "Pan8", "Pan16", "PitchTrack", "PowerADSR", "RegEx", "Sigmund", + "Spectacle", "WinFuncEnv", "WPDiodeLadder", "WPKorg35" ], + // group name + "Chugins Library", + // file name + "chugins", + // group descriptions + "Base chugins library offering unit generators and utilities." +); + // generate doc.outputToDir( ".", "ChucK Class Library Reference" );