diff --git a/docs/accordproject-template.md b/docs/accordproject-template.md index fb7c2543..3d970507 100644 --- a/docs/accordproject-template.md +++ b/docs/accordproject-template.md @@ -207,6 +207,8 @@ Let's look at each component of the template triangle, starting with the text. Build your first smart legal contract templates, either [online](tutorial-studio.md) with Template Studio, or by [installing Cicero](started-installation.md). +Learn about composing full contracts (advanced markup, modularity, embedded expressions) in [Full Contracts](full-contracts.md). + Explore [sample templates](started-resources.md) and other resources in the rest of this documentation. If some of technical words are unfamiliar, please consult the [Glossary](ref-glossary.md) for more detailed explanations. diff --git a/docs/full-contracts.md b/docs/full-contracts.md new file mode 100644 index 00000000..56153adf --- /dev/null +++ b/docs/full-contracts.md @@ -0,0 +1,58 @@ +--- +id: full-contracts +title: Full Contracts +--- + +This page summarizes support for building full contracts using Accord Project templates, with pointers to detailed guides. + +## Advanced Template Markup + +Templatemark lets you structure rich, parameterized legal text: + +- Variables and formatting using `{{ variable }}` +- Conditionals and branches using `{{#if}}...{{/if}}` +- Lists and repetition using `{{#ulist}}`, `{{#olist}}`, and `{{#each}}` +- Subclauses/sections using block constructs + +See: +- Markup preliminaries: `docs/markup-preliminaries.md` +- Templatemark reference: `docs/markup-templatemark.md` +- CiceroMark/markdown semantics: `docs/markup-ciceromark.md`, `docs/markup-commonmark.md` + +## Contract Modularity + +Break large agreements into reusable parts: + +- Import models across namespaces in `.cto` files +- Compose templates via subclauses and include patterns +- Package reusable clauses/templates in libraries + +See: +- Template overview: `docs/accordproject-template.md` +- Tutorial and library: `docs/tutorial-templates.md`, `docs/tutorial-library.md` + +## Embedded Expressions in Templates + +Embed Ergo expressions to compute values at render or execution time using `{{% ... %}}` blocks: + +- Inline calculations (e.g., dates, amounts) +- Conditional text and derived fields + +See: +- Ergo logic: `docs/logic-ergo.md`, `docs/logic-simple-expr.md`, `docs/logic-advanced-expr.md` +- Statements and modules: `docs/logic-stmt.md`, `docs/logic-module.md` + +## End-to-end: From Model to Executable Contract + +Typical workflow: + +1. Define data with Concerto models (`.cto`) +2. Author the template text with Templatemark (variables, lists, conditionals) +3. Implement logic in Ergo (embedded expressions and/or separate modules) +4. Package and test with Cicero CLI/API + +See getting started and tutorials: +- Installation and hello world: `docs/started-installation.md`, `docs/started-hello.md` +- Create and run templates: `docs/tutorial-templates.md`, `docs/tutorial-create.md`, `docs/tutorial-nodejs.md` + + diff --git a/website/babel.config.js b/website/babel.config.js new file mode 100644 index 00000000..56bc3598 --- /dev/null +++ b/website/babel.config.js @@ -0,0 +1,5 @@ +module.exports = { + presets: [require.resolve('@docusaurus/core/lib/babel/preset')], +}; + + diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js new file mode 100644 index 00000000..703a58c8 --- /dev/null +++ b/website/docusaurus.config.js @@ -0,0 +1,67 @@ +// Docusaurus v2 configuration migrated from v1 siteConfig.js +// Minimal viable config; follow-ups: Algolia, custom highlight, users page + +/** @type {import('@docusaurus/types').Config} */ +const config = { + title: 'Accord Project', + tagline: 'Documentation', + url: 'https://docs.accordproject.org', + baseUrl: '/', + favicon: 'img/favicon.png', + organizationName: 'accordproject', + projectName: 'techdocs', + + i18n: { defaultLocale: 'en', locales: ['en'] }, + + presets: [ + [ + 'classic', + /** @type {import('@docusaurus/preset-classic').Options} */ ( + { + docs: { + path: '../docs', + routeBasePath: '/', + sidebarPath: require.resolve('./sidebars.js'), + editUrl: 'https://github.com/accordproject/techdocs/edit/main/website/', + showLastUpdateTime: true, + }, + blog: false, + theme: { + customCss: require.resolve('./static/css/main.css'), + }, + } + ), + ], + ], + + themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ + colorMode: { respectPrefersColorScheme: true }, + navbar: { + title: 'Accord Project', + logo: { alt: 'Accord Project', src: 'img/A-MARK-ACCORDPROJECT-ONELINE-white.svg' }, + items: [ + { to: '/', label: 'Documentation', position: 'left' }, + { href: 'https://studio.accordproject.org', label: 'Try Online!', position: 'left' }, + { href: 'https://github.com/accordproject', label: 'GitHub', position: 'right' }, + { type: 'search', position: 'right' }, + ], + }, + footer: { + style: 'dark', + copyright: `Copyright © 2018-${new Date().getFullYear()} Accord Project, LLC.`, + }, + prism: { + theme: require('prism-react-renderer/themes/dracula'), + }, + algolia: { + // Placeholder; requires v2 index/app settings + appId: 'auto', + apiKey: '1679802ddfc315329d6b5f4616b30e51', + indexName: 'accordproject_api', + }, + }), +}; + +module.exports = config; + + diff --git a/website/package.json b/website/package.json index 5d4d1a8a..6b786abb 100644 --- a/website/package.json +++ b/website/package.json @@ -1,25 +1,26 @@ { - "scripts": { - "examples": "docusaurus-examples", - "start": "docusaurus-start", - "build": "docusaurus-build", - "build:api": "./scripts/build_api_md.sh", - "publish-gh-pages": "docusaurus-publish", - "write-translations": "docusaurus-write-translations", - "version": "docusaurus-version", - "rename-version": "docusaurus-rename-version" - }, + "name": "accordproject-techdocs", + "private": true, "description": "Technical Documentation for the Accord Project", "license": "Apache-2.0", "repository": { "type": "git", "url": "https://github.com/accordproject/techdocs.git" }, + "scripts": { + "start": "docusaurus start", + "build": "docusaurus build", + "serve": "docusaurus serve", + "swizzle": "docusaurus swizzle", + "build:api": "./scripts/build_api_md.sh" + }, "dependencies": { + "@docusaurus/core": "^2.4.3", + "@docusaurus/preset-classic": "^2.4.3", + "react": "^18.2.0", + "react-dom": "^18.2.0", "axios": "^0.21.2", - "docusaurus": "^1.14.7", - "qs": "^6.9.6", - "remarkable-admonitions": "^0.2.2" + "qs": "^6.9.6" }, "devDependencies": { "jsdoc-to-markdown": "^7.1.1" diff --git a/website/sidebars.js b/website/sidebars.js new file mode 100644 index 00000000..7abd2f52 --- /dev/null +++ b/website/sidebars.js @@ -0,0 +1,8 @@ +/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ +const sidebars = { + docs: [{ type: 'autogenerated', dirName: '.' }], +}; + +module.exports = sidebars; + + diff --git a/website/src/pages/index.js b/website/src/pages/index.js new file mode 100644 index 00000000..d66d5602 --- /dev/null +++ b/website/src/pages/index.js @@ -0,0 +1,21 @@ +import React from 'react'; +import Layout from '@theme/Layout'; +import Link from '@docusaurus/Link'; + +export default function Home() { + return ( + +
+

Accord Project Documentation

+

Welcome! Explore the docs using the sidebar or start here:

+

+ + Go to Overview + +

+
+ + ); +} + + diff --git a/website/versioned_docs/version-0.12/accordproject-resources.md b/website/versioned_docs/version-0.12/accordproject-resources.md index 658ba6dd..627e8080 100644 --- a/website/versioned_docs/version-0.12/accordproject-resources.md +++ b/website/versioned_docs/version-0.12/accordproject-resources.md @@ -9,17 +9,17 @@ original_id: accordproject-resources - The Main Web site includes latest news, links to working groups, organizational announcements, etc. : https://www.accordproject.org - This Technical Documentation: https://docs.accordproject.org - Recording of Working Group discussions, Tutorial Videos are on available on Vimeo: https://vimeo.com/accordproject -- Accord Project's [Slack](https://accord-project.slack.com/) +- Accord Project's [Discord](https://discord.gg/Zm99SKhhtA) ## Cicero Resources - GitHub: https://github.com/accordproject/cicero -- Slack [Channel](https://accord-project.slack.com/messages/CA08NAHQS/details/) +- Join our Cicero discussions on [Discord](https://discord.gg/Zm99SKhhtA) - Technical Questions and Answers on [Stack Overflow](https://stackoverflow.com/questions/tagged/cicero) ## Ergo Resources - GitHub: https://github.com/accordproject/ergo - The [Ergo Language Guide](logic-ergo) is a good place to get started with Ergo. -- Slack [Channel](https://accord-project.slack.com/messages/C9HLJHREG/details/) +- Join our Ergo discussions on [Discord](https://discord.gg/Zm99SKhhtA) diff --git a/website/versioned_docs/version-0.12/accordproject-tooling.md b/website/versioned_docs/version-0.12/accordproject-tooling.md index be961aff..7d3f8ed9 100644 --- a/website/versioned_docs/version-0.12/accordproject-tooling.md +++ b/website/versioned_docs/version-0.12/accordproject-tooling.md @@ -27,7 +27,7 @@ A simple Emacs mode for Ergo can be found in the [ergo-mode](https://github.com/ A simple VIM mode for Ergo can be found in the [ergo.vim](https://github.com/accordproject/ergo/tree/master/ergo.vim) directory in the Ergo source code on GitHub. -> Those are not maintained as actively as the rest of the Accord Project. If you know emacs lisp or are a VIM user and would like to contribute, please contact us on the Accord Project Slack or directly through GitHub! +> Those are not maintained as actively as the rest of the Accord Project. If you know emacs lisp or are a VIM user and would like to contribute, please contact us on the Accord Project Discord or directly through GitHub! ## Template Studio diff --git a/website/versioned_docs/version-0.12/accordproject.md b/website/versioned_docs/version-0.12/accordproject.md index eef71b32..2d0d4449 100644 --- a/website/versioned_docs/version-0.12/accordproject.md +++ b/website/versioned_docs/version-0.12/accordproject.md @@ -74,7 +74,7 @@ Several tools are also available to facilitate authoring of Accord Project templ The Accord Project technology is being developed as open source. All the software packages are being actively maintained on [GitHub](https://github.com/accordproject) and we encourage organizations and individuals to contribute requirements, documentation, issues, new templates, and code. -Join the Accord Project Technology Working Group Slack channel to get involved! +Join the Accord Project Technology Working Group on Discord to get involved! ## Try Accord Project Online diff --git a/website/versioned_docs/version-0.20/accordproject-business.md b/website/versioned_docs/version-0.20/accordproject-business.md index 0e8469e7..d9034068 100644 --- a/website/versioned_docs/version-0.20/accordproject-business.md +++ b/website/versioned_docs/version-0.20/accordproject-business.md @@ -27,6 +27,6 @@ If your organization wants to become a member of the Accord Project, please [joi If you are new to the Accord Project, the best place to start is our [Online Tour](started-studio). This video is a great way to see the Accord Project in action! If you want to read more about the key concepts behind the Accord Project technology (or learn more about the template model), please read the [Key Concepts](accordproject-concepts) page. This will allow you to understand the three components of a template (text, model, and logic) and how they work together. -If any of the technical terms are confusing or hard to understand, we have a [Glossary](ref-glossary) page that may help you. If there are any concepts or terms that you want to include in the Glossary, please join our [slack channel](https://accord-project-slack-signup.herokuapp.com/) and make suggestions! +If any of the technical terms are confusing or hard to understand, we have a [Glossary](ref-glossary) page that may help you. If there are any concepts or terms that you want to include in the Glossary, please join our [Discord server](https://discord.gg/Zm99SKhhtA) and make suggestions! If you want to create a template yourself, please see [Authoring in Template Studio](tutorial-latedelivery) for a step-by-step guide on how to create your first template. The tutorial will provide an accessible starting point for those without significant development experience to begin building smart legal contracts using the Accord Project technology. diff --git a/website/versioned_docs/version-0.20/accordproject-developers.md b/website/versioned_docs/version-0.20/accordproject-developers.md index e1b191af..7be468c7 100644 --- a/website/versioned_docs/version-0.20/accordproject-developers.md +++ b/website/versioned_docs/version-0.20/accordproject-developers.md @@ -10,7 +10,7 @@ The Accord Project provides a universal format for smart legal contracts, and th Developers can contribute by converting legal text into corresponding computer code, creating Accord Project templates to be used by lawyers and businesses. In addition, developers can provide input on the development of its technology stack: language, models, templating, and other tools. -If this interests you, please visit our [Technology Working Group](https://www.accordproject.org/working-groups/technology) page, and join our [slack channel](https://accord-project-slack-signup.herokuapp.com/)! +If this interests you, please visit our [Technology Working Group](https://www.accordproject.org/working-groups/technology) page, and join our [Discord server](https://discord.gg/Zm99SKhhtA)! ## How to navigate this documentation? diff --git a/website/versioned_docs/version-0.20/model-api.md b/website/versioned_docs/version-0.20/model-api.md index 2a1200cb..4b9c8640 100644 --- a/website/versioned_docs/version-0.20/model-api.md +++ b/website/versioned_docs/version-0.20/model-api.md @@ -13,6 +13,8 @@ npm install @accordproject/concerto-core@0.20 --save Below are examples of API use. +> Note: The Concerto "functional API" is not available in Concerto 0.20.x. Use the class-based APIs illustrated in this page. References you may see to a functional API apply to later 1.x alpha builds and not to 0.20.x. + ## Create a Concerto File ```js diff --git a/website/versioned_docs/version-0.20/model-relationships.md b/website/versioned_docs/version-0.20/model-relationships.md index abc0eaff..d965bae8 100644 --- a/website/versioned_docs/version-0.20/model-relationships.md +++ b/website/versioned_docs/version-0.20/model-relationships.md @@ -20,7 +20,7 @@ Relationships must be resolved to retrieve an instance of the object being refer A property of a class may be declared as a relationship using the `-->` syntax instead of the `o` syntax. The `o` syntax declares that the class contains (has-a) property of that type, whereas the `-->` syntax declares a typed pointer to an external identifiable instance. -In this example, the model declares that an `Order` has-an array of reference to `OrderLines`. Deleting the `Order` has no impact on the `OrderLine`. When the `Order` is serialized the JSON only the IDs of the `OrderLines` are stored within the `Order`, not the `OrderLines` themselves. +In this example, the model declares that an `Order` has an array of references to `OrderLines`. Deleting the `Order` has no impact on the `OrderLine`. When the `Order` is serialized to JSON, only the IDs of the `OrderLines` are stored within the `Order`, not the `OrderLines` themselves. ```js asset OrderLine identified by orderLineId { diff --git a/website/versioned_docs/version-0.20/started-resources.md b/website/versioned_docs/version-0.20/started-resources.md index 823f7a2d..f61803d3 100644 --- a/website/versioned_docs/version-0.20/started-resources.md +++ b/website/versioned_docs/version-0.20/started-resources.md @@ -9,7 +9,7 @@ original_id: started-resources - The Main Web site includes latest news, links to working groups, organizational announcements, etc. : https://www.accordproject.org - This Technical Documentation: https://docs.accordproject.org - Recording of Working Group discussions, Tutorial Videos are available on Vimeo: https://vimeo.com/accordproject -- Join the [Accord Project Slack](https://accord-project-slack-signup.herokuapp.com) to get involved! +- Join the [Accord Project Discord](https://discord.gg/Zm99SKhhtA) to get involved! ## User Content @@ -38,16 +38,16 @@ Accord Project is also developing tools to help with authoring, testing and runn All the Accord Project technology is being developed as open source. The software packages are being actively maintained on [GitHub](https://github.com/accordproject) and we encourage organizations and individuals to contribute requirements, documentation, issues, new templates, and code. -Join us on the [#technology-wg Slack channel](https://accord-project-slack-signup.herokuapp.com) for technical discussions and weekly updates. +Join us on the [#technology-wg Discord channel](https://discord.gg/Zm99SKhhtA) for technical discussions and weekly updates. ### Cicero - GitHub: https://github.com/accordproject/cicero -- [Cicero Slack Channel](https://accord-project.slack.com/messages/CA08NAHQS/details/) +- Join our Cicero discussions on [Discord](https://discord.gg/Zm99SKhhtA) - Technical Questions and Answers on [Stack Overflow](https://stackoverflow.com/questions/tagged/cicero) ### Ergo - GitHub: https://github.com/accordproject/ergo - The [Ergo Language Guide](logic-ergo) is a good place to get started with Ergo. -- [Ergo Slack Channel](https://accord-project.slack.com/messages/C9HLJHREG/details/) +- Join our Ergo discussions on [Discord](https://discord.gg/Zm99SKhhtA) diff --git a/website/versioned_docs/version-0.21/accordproject-faq.md b/website/versioned_docs/version-0.21/accordproject-faq.md index a792922c..6d39218b 100644 --- a/website/versioned_docs/version-0.21/accordproject-faq.md +++ b/website/versioned_docs/version-0.21/accordproject-faq.md @@ -47,7 +47,7 @@ The purpose of the Accord Project is to establish and maintain a common and cons ### How can I get involved? -The Accord Project Community is developing several working groups focusing on different applications of smart contracts. The working groups have frequent calls and use the Accord Project’s Slack group chat application (join by clicking [here](https://accord-project-slack-signup.herokuapp.com/)) for discussion. The dates, dial-in instructions, and agendas for the working groups are all listed in the Project’s public calendar and typically also in working group’s respective slack channels. +The Accord Project Community is developing several working groups focusing on different applications of smart contracts. The working groups have frequent calls and use the Accord Project’s Discord group chat application (join by clicking [here](https://discord.gg/Zm99SKhhtA)) for discussion. The dates, dial-in instructions, and agendas for the working groups are all listed in the Project’s public calendar and typically also in working groups’ respective Discord channels. A primary purpose of the working groups is to develop a universally accessible and widely used open source library of modular, smart legal contracts, smart templates and models that reflect input from the community. Smart legal contract templates are built according to the Project’s [Cicero Specification](https://github.com/accordproject/cicero). diff --git a/website/versioned_docs/version-0.21/accordproject.md b/website/versioned_docs/version-0.21/accordproject.md index 8d4aad3e..08433624 100644 --- a/website/versioned_docs/version-0.21/accordproject.md +++ b/website/versioned_docs/version-0.21/accordproject.md @@ -41,7 +41,7 @@ The Accord Project provides a universal format for smart legal contracts, and th The Accord Project is developing tools including a [Visual Studio Code plugin](https://marketplace.visualstudio.com/items?itemName=accordproject.cicero-vscode-extension), [React based web components](https://github.com/accordproject/web-components) and a command line interface for working with Accord Project Contracts. You can integrate contracts into existing applications, create new applications or simply assist lawyers with developing applications with the Ergo language. -There is a welcoming community on Slack that is eager to help. [Join our Community](https://www.accordproject.org/membership/) +There is a welcoming community on Discord that is eager to help. [Join our Community](https://discord.gg/Zm99SKhhtA) ## About this documentation diff --git a/website/versioned_docs/version-0.21/model-api.md b/website/versioned_docs/version-0.21/model-api.md index 615e041d..d041ffb6 100644 --- a/website/versioned_docs/version-0.21/model-api.md +++ b/website/versioned_docs/version-0.21/model-api.md @@ -13,6 +13,8 @@ npm install @accordproject/concerto-core --save Below are examples of API use. +> Note: The Concerto "functional API" discussed in some materials was experimental around the 1.0.0-alpha releases. For Concerto 0.21.x, use the class-based APIs shown below. If you are using a 1.x alpha with the functional API, refer to the matching versioned documentation for that release. + ## Validating JSON data using a Model ```js diff --git a/website/versioned_docs/version-0.21/model-relationships.md b/website/versioned_docs/version-0.21/model-relationships.md index a78271e3..e3f9a10d 100644 --- a/website/versioned_docs/version-0.21/model-relationships.md +++ b/website/versioned_docs/version-0.21/model-relationships.md @@ -22,7 +22,7 @@ Relationships must be resolved to retrieve an instance of the object being refer A property of a class may be declared as a relationship using the `-->` syntax instead of the `o` syntax. The `o` syntax declares that the class contains (has-a) property of that type, whereas the `-->` syntax declares a typed pointer to an external identifiable instance. -In this example, the model declares that an `Order` has-an array of reference to `OrderLines`. Deleting the `Order` has no impact on the `OrderLine`. When the `Order` is serialized the JSON only the IDs of the `OrderLines` are stored within the `Order`, not the `OrderLines` themselves. +In this example, the model declares that an `Order` has an array of references to `OrderLines`. Deleting the `Order` has no impact on the `OrderLine`. When the `Order` is serialized to JSON, only the IDs of the `OrderLines` are stored within the `Order`, not the `OrderLines` themselves. ```js asset OrderLine identified by orderLineId { diff --git a/website/versioned_docs/version-0.21/started-resources.md b/website/versioned_docs/version-0.21/started-resources.md index 51fba9de..ba5fc0f5 100644 --- a/website/versioned_docs/version-0.21/started-resources.md +++ b/website/versioned_docs/version-0.21/started-resources.md @@ -9,7 +9,7 @@ original_id: started-resources - The Main Web site includes latest news, links to working groups, organizational announcements, etc. : https://www.accordproject.org - This Technical Documentation: https://docs.accordproject.org - Recording of Working Group discussions, Tutorial Videos are available on Vimeo: https://vimeo.com/accordproject -- Join the [Accord Project Slack](https://accord-project-slack-signup.herokuapp.com) to get involved! +- Join the [Accord Project Discord](https://discord.gg/Zm99SKhhtA) to get involved! ## User Content @@ -38,16 +38,16 @@ Accord Project is also developing tools to help with authoring, testing and runn All the Accord Project technology is being developed as open source. The software packages are being actively maintained on [GitHub](https://github.com/accordproject) and we encourage organizations and individuals to contribute requirements, documentation, issues, new templates, and code. -Join us on the [#technology-wg Slack channel](https://accord-project-slack-signup.herokuapp.com) for technical discussions and weekly updates. +Join us on the [#technology-wg Discord channel](https://discord.gg/Zm99SKhhtA) for technical discussions and weekly updates. ### Cicero - GitHub: https://github.com/accordproject/cicero -- [Cicero Slack Channel](https://accord-project.slack.com/messages/CA08NAHQS/details/) +- Join our Cicero discussions on [Discord](https://discord.gg/Zm99SKhhtA) - Technical Questions and Answers on [Stack Overflow](https://stackoverflow.com/questions/tagged/cicero) ### Ergo - GitHub: https://github.com/accordproject/ergo - The [Ergo Language Guide](logic-ergo) is a good place to get started with Ergo. -- [Ergo Slack Channel](https://accord-project.slack.com/messages/C9HLJHREG/details/) +- Join our Ergo discussions on [Discord](https://discord.gg/Zm99SKhhtA) diff --git a/website/versioned_docs/version-0.30.0/model-api.md b/website/versioned_docs/version-0.30.0/model-api.md index 00ab86a7..ed012a03 100644 --- a/website/versioned_docs/version-0.30.0/model-api.md +++ b/website/versioned_docs/version-0.30.0/model-api.md @@ -13,6 +13,8 @@ npm install @accordproject/concerto-core --save Below are examples of API use. +> Note: If you are using a Concerto 1.x release line that exposes a "functional API", ensure you are consulting the matching versioned docs for that alpha/stable version. This page documents the class-based API for the 0.30.x docs set. + ## Validating JSON data using a Model ```js