Skip to content

Commit

Permalink
add ckdoc support for external group; ChuGL external group added to c…
Browse files Browse the repository at this point in the history 
…kdoc gen script
  • Loading branch information
@gewang
gewang committed Apr 17, 2024
1 parent 13d9e0a commit b770764
Show file tree
Hide file tree
Showing 3 changed files with 152 additions and 24 deletions.
131 changes: 120 additions & 11 deletions src/core/ulib_doc.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 );
Expand Down Expand Up @@ -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.";
Expand Down Expand Up @@ -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;
};


Expand Down Expand Up @@ -737,22 +749,43 @@ string CKDocHTMLOutput::renderIndex( const string & title, const vector<CKDocGro
for( t_CKINT i = 0; i < groups.size(); i++ )
{
CKDocGroup * group = groups[i];
// type A or B output | 1.5.2.4 (ge, azaday) added
// A == normal; B == group points to external CKDoc, e.g., ChuGL
t_CKBOOL typeA = group->types.size() != 0;

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";

// 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 << "<h2><a href=\"" << group->shortName << ".html\">";
else sout << "<h2><a target=\"_blank\" href=\"" << group->shortName << "\">";
sout << 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++ )
// 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 << "<a href=\"" << group->shortName << ".html#" << type->base_name << "\" class=\"" << cssClass << "\">" << type->base_name << "</a>\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->base_name << "\" class=\"" << cssClass << "\">" << type->base_name << "</a>\n";
}
}
else // type B | 1.5.2.4 (ge, azaday) added
{
sout << "<div class=\"index_group_external\">\n";
sout << "<p>\n";
sout << group->longDesc << "\n";
}

sout << "</p>\n";
sout << "</div>\n";
sout << "<div class=\"clear\"></div>\n";
Expand Down Expand Up @@ -901,6 +934,36 @@ t_CKBOOL CKDoc::addGroup( const vector<Chuck_Type *> & 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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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\
Expand Down
9 changes: 7 additions & 2 deletions src/core/ulib_doc.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<Chuck_Type *> & 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
Expand Down
36 changes: 25 additions & 11 deletions src/scripts/ckdoc/gen-all.ck
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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: <a target=\"_blank\" href=\"../../chugl/\">ChuGL homepage</a> | <a target=\"_blank\" href=\"../../chugl/api\">ChuGL API Reference</a>)"
);

// add group
Expand Down Expand Up @@ -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" );

Expand Down

0 comments on commit b770764

Please sign in to comment.