Skip to content

Instantly share code, notes, and snippets.

@ChrisRus
Last active January 30, 2016 00:31
Show Gist options
  • Save ChrisRus/685c45e7c26a424f6471 to your computer and use it in GitHub Desktop.
Save ChrisRus/685c45e7c26a424f6471 to your computer and use it in GitHub Desktop.
Programmatically-generated README.md for a "Filter" function object created w/Encapsule/arccore.filter.create factory (https://github.com/Encapsule/jbus-common-filter/blob/master/README.md). Document generated w/Encapsule/arctools CLI 'arc_doc_filter' script.

Filter 'J2OZ54OMTYi1VMxI9GHQeA'

Operation: J2OZ54OMTYi1VMxI9GHQeA
Input type: 0Eq6gktDQY5a4cneQ1siFg
Output type: output filter disabled
Classification: subsystem input stage

JSX Compiler

Compile ReactJS JSX components into JavaScript bundles via Webpack and Babel.

Filter 'J2OZ54OMTYi1VMxI9GHQeA' is a normalized function object constructed with the Encapsule/arccore Filter Factory that implements a subsystem input stage operation via its request method.

Request Format

Operation 'J2OZ54OMTYi1VMxI9GHQeA' is invoked via filter object method request.

Input filter spec 0Eq6gktDQY5a4cneQ1siFg JSON:

{
    "____label": "JSX Compiler Request",
    "____types": "jsObject",
    "projectDescriptor": {
        "____label": "Project Config Descriptor (input)",
        "____description": "Developer-defined project configuration descriptor object input.",
        "____types": "jsObject",
        "dirs": {
            "____label": "Directory Paths",
            "____description": "Input and output paths used by the project build and runtime.",
            "____types": "jsObject",
            "package": {
                "____label": "Package Directory",
                "____description": "Directory path that contains your package.json manifest. This directory is used as the root directory and project anchor.",
                "____accept": "jsString"
            },
            "input": {
                "____label": "Input Directories",
                "____description": "Input directory paths.",
                "____types": "jsObject",
                "____defaultValue": {},
                "pages": {
                    "____label": "Page Input Directory",
                    "____description": "Directory path to be used for locating sources for building pages.",
                    "____accept": "jsString",
                    "____defaultValue": "./SOURCES/pages"
                }
            },
            "output": {
                "____label": "Output Directories",
                "____description": "Output directory paths.",
                "____types": "jsObject",
                "____defaultValue": {},
                "pages": {
                    "____label": "Page Output Directory",
                    "____description": "Directory to write and serve generated pages from.",
                    "____accept": "jsString",
                    "____defaultValue": "./BUILD/pages"
                }
            }
        },
        "org": {
            "____label": "Organization Descriptor",
            "____description": "Information about your organization.",
            "____types": "jsObject",
            "____defaultValue": {
                "name": "Encapsule.io",
                "location": "Bellevue, WA USA",
                "email": "cdr@encapsule.io"
            },
            "name": {
                "____label": "Organization Name",
                "____description": "The name of your company, organization, or group.",
                "____accept": "jsString"
            },
            "location": {
                "____label": "Organization Location",
                "____description": "The location of your organization.",
                "____accept": "jsString"
            },
            "email": {
                "____label": "Organization E-mail",
                "____description": "Public admin contact e-mail for your organization.",
                "____accept": "jsString"
            }
        },
        "site": {
            "____label": "Site Descriptor",
            "____description": "Information about this specific website.",
            "____types": "jsObject",
            "____defaultValue": {},
            "baseurl": {
                "____label": "Site Base URL",
                "____description": "The base URL this website will be published at.",
                "____accept": "jsString",
                "____defaultValue": "https://mysite.com"
            },
            "title": {
                "____label": "Site Title",
                "____description": "A short site title (used in the Browser title bar)",
                "____accept": "jsString",
                "____defaultValue": "My Site"
            },
            "description": {
                "____label": "Site Description",
                "____description": "A description of this website (added to every page's meta tags).",
                "____accept": "jsString",
                "____defaultValue": "Please add a description of your website."
            },
            "keywords": {
                "____label": "Site Keywords",
                "____description": "An array of keywords germane to this website (added to every page's meta tags).",
                "____types": "jsArray",
                "____defaultValue": [
                    "Encapsule.io",
                    "Node.js",
                    "HTML5",
                    "JavaScript",
                    "automation",
                    "consulting"
                ],
                "keyword": {
                    "____label": "Site Keyword",
                    "____description": "A word germane to this website.",
                    "____accept": "jsString"
                }
            }
        },
        "pages": {
            "____label": "Pages Map",
            "____description": "A hashtable associating page aliases with page route descriptors.",
            "____types": "jsObject",
            "____asMap": true,
            "routeDescriptor": {
                "____label": "Route Descriptor",
                "____description": "An object that declares meta-data required to generate and route the site's primary pages.",
                "____types": "jsObject",
                "title": {
                    "____label": "Page Title",
                    "____description": "A short title of the page (used in the browser title bar)",
                    "____accept": "jsString"
                },
                "description": {
                    "____label": "Page Description",
                    "____description": "A description of this page.",
                    "____accept": "jsString"
                },
                "tooltip": {
                    "____label": "Page Tooltip",
                    "____description": "A short tooltip to display when people mouse over links to this page.",
                    "____accept": "jsString"
                },
                "routes": {
                    "____label": "Routes Vector",
                    "____description": "An array of page route assignments.",
                    "____types": "jsArray",
                    "____defaultValue": [],
                    "route": {
                        "____label": "Route String",
                        "____description": "A page route assignment.",
                        "____accept": "jsString"
                    }
                },
                "routePeerRank": {
                    "____label": "Route Peer Rank",
                    "____description": "Order peer pages below common parent route in ascending rank order. Negative rank drops page from generated menus and sitemap.",
                    "____accept": "jsNumber",
                    "____defaultValue": 0
                },
                "routeMethods": {
                    "____label": "Route Methods",
                    "____description": "An array of HTTP methods the server should provide for this page.",
                    "____types": "jsArray",
                    "____defaultValue": [
                        "GET"
                    ],
                    "httpMethod": {
                        "____label": "HTTP Method",
                        "____description": "An HTTP method name.",
                        "____accept": "jsString",
                        "____inValueSet": [
                            "OPTIONS",
                            "GET",
                            "HEAD",
                            "POST",
                            "PUT",
                            "DELETE",
                            "TRACE",
                            "CONNECT"
                        ]
                    }
                },
                "sourcesDirectory": {
                    "____label": "Sources Directory",
                    "____description": "The local filesystem directory where this page's sources are stored.",
                    "____accept": "jsString",
                    "____defaultValue": "<bad/missing pathname>"
                }
            }
        },
        "collections": {
            "____label": "Page Collections Table",
            "____description": "A map associating a page with a collection of auto-generated subpages.",
            "____types": "jsObject",
            "____asMap": true,
            "collectionDescriptor": {
                "____label": "Collection Descriptor",
                "____description": "Information about the page collection.",
                "____types": "jsObject",
                "collectionPage": {
                    "____label": "Collection Page",
                    "____description": "The name of the page template to use to generate each subpage in the collection.",
                    "____accept": "jsString"
                }
            }
        }
    },
    "options": {
        "____label": "Webpack Config Generator Options",
        "____description": "Options specific to this filter that are used to generate a Webpack configuration object.",
        "____types": "jsObject",
        "target": {
            "____accept": "jsString",
            "____inValueSet": [
                "node",
                "web"
            ],
            "____defaultValue": "web"
        },
        "externals": {
            "____label": "External Module Bundle List",
            "____description": "Optional array of plain module names whose absolute paths are to be located in node_modules and bundled in the compiled output.",
            "____types": [
                "jsUndefined",
                "jsArray"
            ],
            "plainModuleName": {
                "____label": "Plain Module Name",
                "____description": "External module name stripped of path.",
                "____accept": "jsString"
            }
        }
    }
}

Response Format

All filters return a normalized response object with the following pseudo-object format:

{ error: string | null, result: variant }

Iff response.error is null then response.result is valid. Otherwise, response.error is a string explaining what went wrong.

Iff response.error is not null (i.e. an error occurred), then response.result may contain information that's useful for fault diagnosis.

Iff no error occurred (i.e. response.error === null) then the format of response.result specified by the filter's output filter specification as detailed in the next section.

Output filter spec output filter disabled JSON:

output filter disabled

Generated Fri Jan 29 2016 15:36:30 GMT-0800 (PST) by [Encapsule/arctools](https://github.com/Encapsule/arctools/) v0.0.6.
@ChrisRus
Copy link
Author

There's enough information in a "Filter Spec" JSON object to create lovely human readable docs. As the creator of Filter Spec's I actually find the raw syntax best for quick reference. But the "prose" version should be available for those unfamiliar with the library. Working on that...

More about Filter Spec JSON syntax: https://github.com/Encapsule/jbus-common-filter/blob/master/docs/02-filter-spec-guide.md

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment