Skip to content

Commit

Permalink
Tidied up DefaultTheme, fixed #9
Browse files Browse the repository at this point in the history
  • Loading branch information
@sebastian-lenz
sebastian-lenz committed Jun 15, 2014
1 parent b87e339 commit 9b99207
Show file tree
Hide file tree
Showing 3 changed files with 853 additions and 321 deletions.
244 changes: 222 additions & 22 deletions bin/typedoc.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1527,38 +1527,237 @@ declare module TypeDoc.Output {
}
}
declare module TypeDoc.Output {
/**
* Base class of all themes.
*
* A theme defines the logical and graphical output of a documentation. Themes are
* directories containing a ```theme.js``` file defining a [[BaseTheme]] subclass and a
* series of subdirectories containing templates and assets. You can select a theme
* through the ```--theme <path/to/theme>``` commandline argument.
*
* The theme class controls which files will be created through the [[BaseTheme.getUrls]]
* function. It returns an array of [[UrlMapping]] instances defining the target files, models
* and templates to use. Additionally themes can subscribe to the events emitted by
* [[Renderer]] to control and manipulate the output process.
*
* The default file structure of a theme looks like this:
*
* - ```/assets/```<br>
* Contains static assets like stylesheets, images or javascript files used by the theme.
* The [[AssetsPlugin]] will deep copy this directory to the output directory.
*
* - ```/layouts/```<br>
* Contains layout templates that the [[LayoutPlugin]] wraps around the output of the
* page template. Currently only one ```default.hbs``` layout is supported. Layout templates
* receive the current [[OutputPageEvent]] instance as their handlebars context. Place the
* ```{{{contents}}}``` variable to render the actual body of the document within this template.
*
* - ```/partials/```<br>
* Contains partial templates that can be used by other templates using handlebars partial
* syntax ```{{> partial-name}}```. The [[PartialsPlugin]] loads all files in this directory
* and combines them with the partials of the default theme.
*
* - ```/templates/```<br>
* Contains the main templates of the theme. The theme maps models to these templates through
* the [[BaseTheme.getUrls]] function. If the [[Renderer.getTemplate]] function cannot find a
* given template within this directory, it will try to find it in the default theme
* ```/templates/``` directory. Templates receive the current [[OutputPageEvent]] instance as
* their handlebars context. You can access the target model through the ```{{model}}``` variable.
*
* - ```/theme.js```<br>
* A javascript file that returns the definition of a [[BaseTheme]] subclass. This file will
* be executed within the context of TypeDoc, one may directly access all classes and functions
* of TypeDoc. If this file is not present, an instance of [[DefaultTheme]] will be used to render
* this theme.
*/
class BaseTheme {
/**
* The renderer this theme is attached to.
*/
public renderer: Renderer;
/**
* The base path of this theme.
*/
public basePath: string;
/**
* Create a new BaseTheme instance.
*
* @param renderer The renderer this theme is attached to.
* @param basePath The base path of this theme.
*/
constructor(renderer: Renderer, basePath: string);
public initialize(): void;
public isOutputDirectory(dirname: string): boolean;
/**
* Test whether the given path contains a documentation generated by this theme.
*
* TypeDoc empties the output directory before rendering a project. This function
* is used to ensure that only previously generated documentations are deleted.
* When this function returns FALSE, the documentation will not be created and an
* error message will be displayed.
*
* Every theme must have an own implementation of this function, the default
* implementation always returns FALSE.
*
* @param path The path of the directory that should be tested.
* @returns TRUE if the given path seems to be a previous output directory,
* otherwise FALSE.
*
* @see [[Renderer.prepareOutputDirectory]]
*/
public isOutputDirectory(path: string): boolean;
/**
* Map the models of the given project to the desired output files.
*
* Every theme must have an own implementation of this function, the default
* implementation always returns an empty array.
*
* @param project The project whose urls should be generated.
* @returns A list of [[UrlMapping]] instances defining which models
* should be rendered to which files.
*/
public getUrls(project: Models.ProjectReflection): Models.UrlMapping[];
/**
* Create a navigation structure for the given project.
*
* A navigation is a tree structure consisting of [[NavigationItem]] nodes. This
* function should return the root node of the desired navigation tree.
*
* The [[NavigationPlugin]] will call this hook before a project will be rendered.
* The plugin will update the state of the navigation tree and pass it to the
* templates.
*
* @param project The project whose navigation should be generated.
* @returns The root navigation item.
*/
public getNavigation(project: Models.ProjectReflection): Models.NavigationItem;
}
}
declare module TypeDoc.Output {
/**
* Defines a mapping of a [[Models.Kind]] to a template file.
*
* Used by [[DefaultTheme]] to map reflections to output files.
*/
interface ITemplateMapping {
kind: any;
/**
* [[DeclarationReflection.kind]] this rule applies to.
*/
kind: TypeScript.PullElementKind[];
/**
* Can this mapping have children or should all further reflections be rendered
* to the defined output page?
*/
isLeaf: boolean;
prefix: string;
/**
* The name of the directory the output files should be written to.
*/
directory: string;
/**
* The name of the template that should be used to render the reflection.
*/
template: string;
}
/**
* Default theme implementation of TypeDoc. If a theme does not provide a custom
* [[BaseTheme]] implementation, this theme class will be used.
*/
class DefaultTheme extends BaseTheme {
/**
* Mappings of reflections kinds to templates used by this theme.
*/
static MAPPINGS: ITemplateMapping[];
public isOutputDirectory(dirname: string): boolean;
private getMapping(reflection);
/**
* Build the urls for the current project.
* Create a new DefaultTheme instance.
*
* @returns An array of url mappings.
* @param renderer The renderer this theme is attached to.
* @param basePath The base path of this theme.
*/
constructor(renderer: Renderer, basePath: string);
/**
* Test whether the given path contains a documentation generated by this theme.
*
* @param path The path of the directory that should be tested.
* @returns TRUE if the given path seems to be a previous output directory,
* otherwise FALSE.
*/
public isOutputDirectory(path: string): boolean;
/**
* Map the models of the given project to the desired output files.
*
* @param project The project whose urls should be generated.
* @returns A list of [[UrlMapping]] instances defining which models
* should be rendered to which files.
*/
public getUrls(project: Models.ProjectReflection): Models.UrlMapping[];
/**
* Create a navigation structure for the given project.
*
* @param project The project whose navigation should be generated.
* @returns The root navigation item.
*/
public getNavigation(project: Models.ProjectReflection): Models.NavigationItem;
/**
* Transform a space separated string into a string suitable to be used as a css class.
* Triggered before the renderer starts rendering a project.
*
* @param event An event object describing the current render operation.
*/
static classify(str: string): string;
private onRendererBegin(event);
/**
* Return a url for the given reflection.
*
* @param reflection The reflection the url should be generated for.
* @param relative The parent reflection the url generation should stop on.
* @param separator The separator used to generate the url.
* @returns The generated url.
*/
static getUrl(reflection: Models.BaseReflection, relative?: Models.BaseReflection, separator?: string): string;
/**
* Return the template mapping fore the given reflection.
*
* @param reflection The reflection whose mapping should be resolved.
* @returns The found mapping or NULL if no mapping could be found.
*/
static getMapping(reflection: Models.DeclarationReflection): ITemplateMapping;
/**
* Build the navigation nodes for the given reflection.
*
* @param reflection The reflection whose navigation node should be created.
* @param parent The parent navigation node.
*/
static buildNavigation(reflection: Models.DeclarationReflection, parent: Models.NavigationItem): void;
/**
* Build the url for the the given reflection and all of its children.
*
* @param reflection The reflection the url should be created for.
* @param urls The array the url should be appended to.
* @returns The altered urls array.
*/
static buildUrls(reflection: Models.DeclarationReflection, urls: Models.UrlMapping[]): Models.UrlMapping[];
/**
* Generate an anchor url for the given reflection and all of its children.
*
* @param reflection The reflection an anchor url should be created for.
* @param container The nearest reflection having an own document.
*/
static applyAnchorUrl(reflection: Models.DeclarationReflection, container: Models.BaseReflection): void;
/**
* Generate the css classes for the given reflection and apply them to the
* [[DeclarationReflection.cssClasses]] property.
*
* @param reflection The reflection whose cssClasses property should be generated.
*/
static applyReflectionClasses(reflection: Models.DeclarationReflection): void;
/**
* Generate the css classes for the given reflection group and apply them to the
* [[ReflectionGroup.cssClasses]] property.
*
* @param group The reflection group whose cssClasses property should be generated.
*/
static applyGroupClasses(group: Models.ReflectionGroup): void;
/**
* Transform a space separated string into a string suitable to be used as a
* css class, e.g. "constructor method" > "Constructor-method".
*/
static toStyleClass(str: string): string;
}
}
declare module TypeDoc.Output {
Expand Down Expand Up @@ -1747,7 +1946,7 @@ declare module TypeDoc.Output {
* An event emitted by the [[Renderer]] class before and after the
* markup of a page is rendered.
*
* This object will be passed as the rendering context to the handlebars template.
* This object will be passed as the rendering context to handlebars templates.
*
* @see [[Renderer.EVENT_BEGIN_PAGE]]
* @see [[Renderer.EVENT_END_PAGE]]
Expand Down Expand Up @@ -1786,7 +1985,9 @@ declare module TypeDoc.Output {
*/
public secondary: Models.NavigationItem[];
/**
* The html content of this page.
* The final html content of this page.
*
* Should be rendered by layout templates and can be modifies by plugins.
*/
public contents: string;
}
Expand All @@ -1813,24 +2014,23 @@ declare module TypeDoc.Output {
}
declare module TypeDoc.Output {
/**
* A plugin that wraps the generated output with a layout template.
* A plugin that exports an index of the project to a javascript file.
*
* Currently only a default layout is supported. The layout must be stored
* as ´layouts/default.hbs´ in the theme directory.
* The resulting javascript file can be used to build a simple search function.
*/
class LayoutPlugin extends BasePlugin {
class JavascriptIndexPlugin extends BasePlugin {
/**
* Create a new LayoutPlugin instance.
* Create a new JavascriptIndexPlugin instance.
*
* @param renderer The renderer this plugin should be attached to.
*/
constructor(renderer: Renderer);
/**
* Triggered after a document has been rendered, just before it is written to disc.
*
* @param page An event object describing the current render operation.
* @param event An event object describing the current render operation.
*/
private onRendererEndPage(page);
private onRendererBegin(event);
}
}
declare module TypeDoc.Output {
Expand All @@ -1840,7 +2040,7 @@ declare module TypeDoc.Output {
* Currently only a default layout is supported. The layout must be stored
* as ´layouts/default.hbs´ in the theme directory.
*/
class LunrPlugin extends BasePlugin {
class LayoutPlugin extends BasePlugin {
/**
* Create a new LayoutPlugin instance.
*
Expand All @@ -1850,9 +2050,9 @@ declare module TypeDoc.Output {
/**
* Triggered after a document has been rendered, just before it is written to disc.
*
* @param event An event object describing the current render operation.
* @param page An event object describing the current render operation.
*/
private onRendererBegin(event);
private onRendererEndPage(page);
}
}
declare module TypeDoc.Output {
Expand Down
Loading

0 comments on commit 9b99207

Please sign in to comment.