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.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.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.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