From e682fe457ce749a8fcd3359182e4a73286d0b484 Mon Sep 17 00:00:00 2001 From: Dan Selman Date: Wed, 29 Jul 2020 22:04:21 +0200 Subject: [PATCH] doc - update instructions Signed-off-by: Dan Selman --- README.md | 408 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 396 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 17b850f..8de5cfc 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,50 @@ -# LSP Example +

+ Accord Project Extension for VSCode +

-Heavily documented sample code for https://code.visualstudio.com/api/language-extensions/language-server-extension-guide +

+ Build Status + GitHub license + + Join the Accord Project Slack + +

-## Functionality +Validates that Cicero templates conform to the [Accord Project Template Specification](https://docs.accordproject.org): -This Language Server works for plain text file. It has the following language features: -- Completions -- Diagnostics regenerated on each file change or configuration change +- Validates the model for the template ('.cto' files), downloading referenced external models as required +- Validates the logic of the template ('.ergo' files) +- Validates that the template archive can be built +- Validates that the 'text/sample.md' file for the template can be parsed using the grammar ('text/grammar.tem.md' file) +- Syntax highlighting for all files -It also includes an End-to-End test. +## For Template Authors -## Structure +If you want to use this plugin: + +1. Download and install VSCode from https://code.visualstudio.com/download +2. Remove any existing versions of the Ergo extension and the Hyperledger Composer extension +3. From the extensions view in VSCode, search for "Accord Project", click the `Install` button to install it + +The extension is available from the Visual Studio Marketplace at https://marketplace.visualstudio.com/items?itemName=accordproject.cicero-vscode-extension + +## Snippets + +### For Concerto + +We provide snippets generation for all the class method present in the Concerto languages. + +| Classes | Prefix | +| :---------- | :---------: | +| Asset | asset | +| Participant | participant | +| Transaction | transaction | +| Concept | concept | +| Enum | enum | + +## For Contributors + +### Structure ``` . @@ -24,7 +58,7 @@ It also includes an End-to-End test. └── server.ts // Language Server entry point ``` -## Running the Sample +### Running - Run `npm install` in this folder. This installs all necessary npm modules in both the client and server folder - Open VS Code on this folder. @@ -33,6 +67,356 @@ It also includes an End-to-End test. - Select `Launch Client` from the drop down. - Run the launch config. - If you want to debug the server as well use the launch configuration `Attach to Server` -- In the [Extension Development Host] instance of VSCode, open a document in 'plain text' language mode. - - Type `j` or `t` to see `Javascript` and `TypeScript` completion. - - Enter text content such as `AAA aaa BBB`. The extension will emit diagnostics for all words in all-uppercase. + +### Manual Build and Install + +Generate the installable VSIX file: + +``` +git clone https://github.com/accordproject/cicero-vscode-extension.git +npm install +npm run package:vsix +``` + +1. Launch VSCode +2. View > Extensions +3. Press the ... and select "Install from VSIX" +4. Browse to the VSIX file +5. Install and restart VSCode +6. Open a .cto or .ergo file + +### Travis CI build + +Developers no longer need a manual build, once you have created a pull request from your private Github repository. The build will be automatically performed by Travis. +A successful build will create an installable VSIX file on the build machine. +The public release version number is defined in the Client package.json file. + +#### Publish Release + +Below are steps for publishing a release. + +1. Go to https://github.com/accordproject/cicero-vscode-extension +2. Click Releases tab +3. Click Draft a new release on the right +4. Type a Tag version in the Tag version field. e.g. v0.5.7.1 +5. Type a Release title in the Release title field e.g v0.5.7.1 +6. Provide a short description of this release under the Write tab +7. Uncheck the box for This is a pre-release at the end of this page +8. Click Publish release button to publish the VSIX file to the VSCode Marketplace + +#### Check the published release + +1. Go to the VSCode Marketplace: https://marketplace.visualstudio.com/ +2. Type Accord Project in the search field and hit return key or search button +3. This will bring you to https://marketplace.visualstudio.com/search?term=Accord%20Project&target=VSCode&category=All%20categories&sortBy=Relevance + +#### Install a new release + +1. Open Visual Studio Code in your desktop +2. Open the Extensions by View-->Extensions or Ctrl(cmd)+Shift+x +3. Search for Accord Project +4. The new published Accord Project plugin is showing on the list +5. Click Install button to install it +6. Update button will be shown if you have already installed the same plugin before. + +## Acknowledgments + +Thanks to our friends at Hyperledger Composer for inspiring us with their existing plugin, +https://github.com/hyperledger/composer-vscode-plugin/ + +--- + +

+ + Accord Project Logo + +

+ +Accord Project is an open source, non-profit, initiative working to transform contract management and contract automation by digitizing contracts. Accord Project operates under the umbrella of the [Linux Foundation][linuxfound]. The technical charter for the Accord Project can be found [here][charter]. + +## Learn More About Accord Project + +### Overview + +- [Accord Project][apmain] +- [Accord Project News][apnews] +- [Accord Project Blog][apblog] +- [Accord Project Slack][apslack] +- [Accord Project Technical Documentation][apdoc] +- [Accord Project GitHub][apgit] + +### Documentation + +- [Getting Started with Accord Project][docwelcome] +- [Concepts and High-level Architecture][dochighlevel] +- [How to use the Cicero Templating System][doccicero] +- [How to Author Accord Project Templates][docstudio] +- [Ergo Language Guide][docergo] + +### Ecosystem + +#### Core libraries: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProjectsPackage nameVersionDescription
Cicero cicero-core npm versionTemplates Core
cicero-cli npm version Cicero CLI
cicero-engine npm versionNode.js VM based implementation of Accord Project Template Specification execution
cicero-server npm versionWraps the Cicero Engine and exposes it as a RESTful service +
cicero-test npm version Testing support for Cicero based on cucumber
cicero-tools npm versionCicero Tools
generator-cicero-template npm versionCode generator for a Cicero Template
Concertoconcerto-core npm version Core Implementation for the Concerto Modeling Language
concerto-tools npm version Tools for the Concerto Modeling Language
concerto-cli npm versioncommand-line interface for Concerto
Ergoergo-clinpm versionErgo CLI
ergo-compilernpm versionErgo compiler
ergo-testnpm versionErgo test
ergo-enginenpm versionErgo engine
Markdownmarkdown-commonnpm versionA framework for transforming markdown
markdown-slatenpm versionTransform markdown to/from CommonMark DOM
markdown-cli npm version CLI for markdown transformations.
markdown-ciceronpm versionCiceroDOM: Markdown extensions for contracts, clauses, variables etc.
markdown-htmlnpm versionTransform CiceroDOM to HTML
+ +#### UI Components: + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProjectsPackage nameVersionDescription
Markdown Editormarkdown-editor + npm versionWYSIWYG rich text web editor that persists text as markdown. Based on Slate.js
Cicero UIcicero-ui npm versionWYSIWYG contract editor, template library browser, error panel component
Concerto UIconcerto-ui npm versionDynamic web forms generated from Concerto models
+ +#### Template Editors: + + + + + + + + + + + + + + + + + + + + + + +
ProjectsCicero ver.Description
Template Studio v1 0.13.4Web UI for creating, editing and testing Accord Project templates
Template Studio v2 0.13.4Web UI for creating, editing and testing Accord Project templates
VSCode Extension0.13.4VS Code extension for editing Cicero templates and Ergo logic
+ +#### Public templates and models: + + + + + + + + + + + + + + + +
ProjectsDescription
ModelsAccord Project Model Library
Template LibraryAccord Project Template Library
+ +#### Documentation: + + + + + + + + + + +
ProjectRepo
Documentationtechdocs
+ +## Contributing + +The Accord Project technology is being developed as open source. All the software packages are being actively maintained on GitHub and we encourage organizations and individuals to contribute requirements, documentation, issues, new templates, and code. + +Find out what’s coming on our [blog][apblog]. + +Join the Accord Project Technology Working Group [Slack channel][apslack] to get involved! + +For code contributions, read our [CONTRIBUTING guide][contributing] and information for [DEVELOPERS][developers]. + +### README Badge + +Using Accord Project? Add a README badge to let everyone know: [![accord project](https://img.shields.io/badge/powered%20by-accord%20project-19C6C8.svg)](https://www.accordproject.org/) + +``` +[![accord project](https://img.shields.io/badge/powered%20by-accord%20project-19C6C8.svg)](https://www.accordproject.org/) +``` + +## License + +Accord Project source code files are made available under the [Apache License, Version 2.0][apache]. +Accord Project documentation files are made available under the [Creative Commons Attribution 4.0 International License][creativecommons] (CC-BY-4.0). + +Copyright 2018-2019 Clause, Inc. All trademarks are the property of their respective owners. See [LF Projects Trademark Policy](https://lfprojects.org/policies/trademark-policy/). + +[apmain]: https://accordproject.org/ +[apworkgroup]: https://calendar.google.com/calendar/event?action=TEMPLATE&tmeid=MjZvYzIzZHVrYnI1aDVzbjZnMHJqYmtwaGlfMjAxNzExMTVUMjEwMDAwWiBkYW5AY2xhdXNlLmlv&tmsrc=dan%40clause.io +[apblog]: https://medium.com/@accordhq +[apnews]: https://www.accordproject.org/news/ +[apgit]: https://github.com/accordproject/ +[apdoc]: https://docs.accordproject.org/ +[apslack]: https://accord-project-slack-signup.herokuapp.com +[docspec]: https://docs.accordproject.org/docs/spec-overview.html +[docwelcome]: https://docs.accordproject.org/docs/accordproject.html +[dochighlevel]: https://docs.accordproject.org/docs/spec-concepts.html +[docergo]: https://docs.accordproject.org/docs/logic-ergo.html +[docstart]: https://docs.accordproject.org/docs/accordproject.html +[doccicero]: https://docs.accordproject.org/docs/basic-use.html +[docstudio]: https://docs.accordproject.org/docs/advanced-latedelivery.html +[contributing]: https://github.com/accordproject/cicero-vscode-extension/blob/master/CONTRIBUTING.md +[developers]: https://github.com/accordproject/cicero-vscode-extension/blob/master/DEVELOPERS.md +[linuxfound]: https://www.linuxfoundation.org +[charter]: https://github.com/accordproject/cicero-vscode-extension/blob/master/CHARTER.md +[npmpkg]: https://www.npmjs.com/package/@accordproject/ergo-cli +[coq]: https://coq.inria.fr +[ocaml]: https://ocaml.org +[qcert]: https://querycert.github.io +[repl]: https://ergorepl.netlify.com +[studio]: https://studio.accordproject.org +[nodejs]: https://nodejs.org/ +[apache]: https://github.com/accordproject/cicero-vscode-extension/blob/master/LICENSE +[creativecommons]: http://creativecommons.org/licenses/by/4.0/ +