{"_id":"@ampretia/composer-opus","_rev":"2-4602d8921523eae9fcd0d8e256b744d9","name":"@ampretia/composer-opus","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@ampretia/composer-opus","version":"0.2.0","description":"Generates documentation packages for Hyperlegder Composer Business Networks","bin":{"opus":"bin/opus"},"main":"index.js","scripts":{"test":"./test/usage/go.sh && cp -r ./test/usage/out/* ./docs/"},"keywords":[],"author":{"name":"MBW"},"license":"Apache-2","devDependencies":{"eslint":"^4.16.0","mermaid":"^7.1.0"},"dependencies":{"chalk":"^2.3.0","composer-admin":"^0.17.4","composer-client":"^0.17.4","debug-stream":"^3.0.1","js-yaml":"^3.10.0","js2flowchart":"^1.1.3","lodash.clonedeep":"^4.5.0","map-stream":"0.0.7","markdown-it":"^8.4.0","markdown-it-anchor":"^4.0.0","mkdirp":"^0.5.1","nunjucks":"^3.0.1","ora":"^1.4.0","prettyoutput":"^1.1.1","rimraf":"^2.6.2","vinyl-fs":"^2.4.4","yargs":"^8.0.2"},"gitHead":"5346c026e5e431dce6bf20325aa7cfb6828856a4","_id":"@ampretia/composer-opus@0.2.0","_npmVersion":"5.5.1","_nodeVersion":"8.9.0","_npmUser":{"name":"calanais","email":"matthew@mh-white.com"},"dist":{"integrity":"sha512-soPBZse6gpASNLPwVhe+1F8rI3Aqt/PEvhLJ16FJsiKaBCqq2IDaO2oHfGU9K0tA4J8g1PEfKs2BZ+zOlLc4iQ==","shasum":"b9fd9ac5aa0edbffcd112ed917208b1aebfd7501","tarball":"https://registry.npmjs.org/@ampretia/composer-opus/-/composer-opus-0.2.0.tgz","fileCount":275,"unpackedSize":9646498,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIBbRbK8H/7cPK1NkYgq/+0fCexIj7MmS6ZmWOqedPTGlAiAC4Be2PE/J5kCnBZdC6U0jK95nLkYNtfzZFSX06mgzcg=="}]},"maintainers":[{"name":"calanais","email":"matthew@mh-white.com"}],"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/composer-opus_0.2.0_1518188130567_0.2734157668703803"},"_hasShrinkwrap":false}},"time":{"created":"2018-02-09T14:55:30.182Z","0.2.0":"2018-02-09T14:55:32.870Z","modified":"2022-04-04T13:52:55.310Z"},"maintainers":[{"name":"calanais","email":"matthew@mh-white.com"}],"description":"Generates documentation packages for Hyperlegder Composer Business Networks","keywords":[],"author":{"name":"MBW"},"license":"Apache-2","readme":"# Hyperledger Composer Opus\r\n\r\nA Proof-Of-Idea to see if the power of template engines, plus the Introspector API, and the NPM meta-data in a BusinessNeworkArchive could be used to generate a set of documentation for the archive.\r\n\r\nThis introspection of all the model files etc to get a set of data that can be then transformed into the desired output.\r\n\r\n\r\n\r\nAll the information is captured so the next step is (a) produce a set of established decorators such as \r\n\r\n```\r\n@docs('This is some docs')\r\nassert fred indetified by id {\r\n  @docs('the primary key')\r\n  o String id\r\n}\r\n```\r\n\r\nThat can be used to provide more in-depth documentation\r\n\r\n## Example\r\n\r\nBest seen with an example.... [https://ampretia.github.io/composer-opus/](https://ampretia.github.io/composer-opus/)\r\n\r\n## Usage\r\n```\r\n$ npm install -g @ampretia/composer-opus\r\n$ opus\r\nOptions:\r\n  -a, --archive  Archive file to document                    [string] [required]\r\n  -o, --outdir   Output Directory                    [string] [default: \"./out\"]\r\n  -c, --config   path to the configuration file[string] [default: \"config.yaml\"]\r\n  --help         Show help                                             [boolean]\r\n\r\n```\r\n\r\nThere is a default template and set of structure already defined as a default. This could be customized to suit and it is not restricted to handling markdown and \r\nhtml.\r\n\r\n## Configuration\r\nThe example site was produced with this configuration file - this is in yaml format as the flow through the system is hierarchical\r\n\r\n```yaml\r\n--- \r\ntasks:\r\n    #  Root task that defines common data for all tasks\r\n    taskid : root\r\n    processor : root\r\n    options :\r\n        outputdir : ${_args.outdir}\r\n        templateroot: ${default.template}\r\n        tempdir : ${default.temp}     \r\n    subtasks :\r\n    #  Use Hyperledger Composer taks to extract all information and setup the context\r\n    -   taskid : ParseNetwork\r\n        processor : composernetwork\r\n        options :\r\n            archive : \"${_args.archive}\"   \r\n    #  Uses multiple templates specified in 'inputdir' & 'pattern' to work on the context and produce markdown output files\r\n    -   taskid : CreateMarkdown\r\n        processor : njk_multi\r\n        options :\r\n            inputdir : \"phase1-markdown\"\r\n            pattern : \"**/*.njk\"\r\n            outputextension : \".md\"\r\n            outputdir : \"${root.tempdir}\"\r\n       \r\n    # From the markdown files that are created previously generate html\r\n    # This is a two step process, files needs to converted into html and then wrapped in\r\n    # the correct header/footer etc. Stream tasks allows the output from one task to go into the second\r\n    -   taskid : HTML\r\n        processor: stream\r\n        options :\r\n            inputdir : \"${root.tempdir}\"\r\n            pattern : \"**/*.md\"\r\n            outputdir : \"${_args.outdir}\"\r\n            streamid : html1          \r\n        subtasks :\r\n            # For each markdown file stream into it this will convert into html and pass on the details via the stream\"          \r\n            -   taskid : markdownhtml\r\n                processor : markdownit\r\n            # Single template to be used to process files via stream along with the context\r\n            -   taskid : htmlrender\r\n                processor : njk_single\r\n                options :\r\n                    inputdir : \"phase2-html\"\r\n                    template : html.default.njk\r\n                    extension: \".html\"\r\n    # Finally need to copy the fixed assets to the output directory \"\r\n    -   taskid : FinalStep\r\n        processor : copy\r\n        options :\r\n            srcdir : \"${root.templateroot}/assets.default/**/*\" \r\n            destdir : \"${_args.outdir}/assets\"  \r\n         \r\n\r\n```\r\n\r\n## Details\r\nAt first glance this is complex, but let's break it down bit by bit. The basic idea is there is a sequence of tasks that will be executed in order. These can form a tree so that it is possible to group the tasks.\r\n\r\n```yaml\r\n--- \r\ntasks:\r\n    #  Root task that defines common data for all tasks\r\n    taskid : root\r\n    processor : root\r\n    options :\r\n        outputdir : ${_args.outdir}\r\n        templateroot: ${default.template}\r\n        tempdir : ${default.temp}     \r\n    subtasks :\r\n```\r\n\r\nThis defines the top level tasks - identified by *taskid* and the *processor* that will be used to handle this task\r\n\r\n> Each task needs a *taskid* and a *processor*\r\n\r\nThis takes some options, namely the *outputdir*, *templateroot* and *tempdir*. These are standard and best left as is. Note the `${_args.outdir}` is taking the output directory from the command line options.\r\n\r\nSub tasks can be defined and appear under the *subtasks*\r\n\r\n```yaml\r\n\r\n    #  Use Hyperledger Composer taks to extract all information and setup the context\r\n    -   taskid : ParseNetwork\r\n        processor : composernetwork\r\n        options :\r\n            archive : \"${_args.archive}\"   \r\n```\r\n\r\nThis is the first subtasked processed using the *composernetwork* processor. This takes the archive specified on the command line and processes it to extract all the data. This is held in an internal 'context'\r\n\r\nThis tasks has no subtasks, so execution moves on.\r\n\r\n```yaml\r\n    #  Uses multiple templates specified in 'inputdir' & 'pattern' to work on the context and produce markdown output files\r\n    -   taskid : CreateMarkdown\r\n        processor : njk_multi\r\n        options :\r\n            inputdir : \"phase1-markdown\"\r\n            pattern : \"**/*.njk\"\r\n            outputextension : \".md\"\r\n            outputdir : \"${root.tempdir}\"\r\n```\r\nA more complex task,but this uses the *njk_multi* processor. Using [nunjucks](https://mozilla.github.io/nunjucks/) a set of templates are processed against the internal context to generate a set of markdown files. \r\n\r\nThe options determine where these are (all relative paths such as the *inputdir* are rooted at the *templateroot* seen earlier on).\r\n\r\nThe output of these files is stored in a temporary location.\r\n\r\nNote that the output of these files is markdown format because (a) that's what the template is set up to produce and (b) because of the extension specified in the options.\r\n\r\nAgain this task has no subtasks\r\n\r\n```yaml\r\n    # From the markdown files that are created previously generate html\r\n    # This is a two step process, files needs to converted into html and then wrapped in\r\n    # the correct header/footer etc. Stream tasks allows the output from one task to go into the second\r\n    -   taskid : HTML\r\n        processor: stream\r\n        options :\r\n            inputdir : \"${root.tempdir}\"\r\n            pattern : \"**/*.md\"\r\n            outputdir : \"${_args.outdir}\"\r\n            streamid : html1          \r\n        subtasks :\r\n            # For each markdown file stream into it this will convert into html and pass on the details via the stream\"          \r\n            -   taskid : markdownhtml\r\n                processor : markdownit\r\n            # Single template to be used to process files via stream along with the context\r\n            -   taskid : htmlrender\r\n                processor : njk_single\r\n                options :\r\n                    inputdir : \"phase2-html\"\r\n                    template : html.default.njk\r\n                    extension: \".html\"\r\n```\r\nThis is the most complex task and makes use of the ability to group tasks together. The aim here is to take the markdown files produced previously, and render these as html. This is a two stage process. First the files need converting from markdown to html, and then the core html needs to be wrapped in headers, footers etc. \r\n\r\nThis is accomplished by a using a *stream* tasks. This takes inputdir, patter, and an outputdir. It reads all the input, passes it to the first subtask, gets the output, passes it to the next subtask before writing it all to the output dir.\r\n\r\nThe first subtask (markdownhtml) does the conversion of each markdown file read into html. \r\nThe second subtask (htmlrender) again uses nunjucks but this is using a single template to transform input to output (basically adding the header)\r\n\r\n```yaml\r\n    # Finally need to copy the fixed assets to the output directory \"\r\n    -   taskid : FinalStep\r\n        processor : copy\r\n        options :\r\n            srcdir : \"${root.templateroot}/assets.default/**/*\" \r\n            destdir : \"${_args.outdir}/assets\"  \r\n```\r\n\r\nFinal step is a copy to move the 'assets' i.e. css files into the correct location.","readmeFilename":"README.md"}