docs(concerto): clarify functional API availability in model-api docs (closes #353)

website/babel.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};
+
+

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;
+
+

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"

website/sidebars.js

@@ -0,0 +1,8 @@
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const sidebars = {
+  docs: [{ type: 'autogenerated', dirName: '.' }],
+};
+
+module.exports = sidebars;
+
+

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 (
+    <Layout title="Accord Project" description="Accord Project Documentation">
+      <main style={{ padding: '3rem 1rem', maxWidth: 960, margin: '0 auto' }}>
+        <h1>Accord Project Documentation</h1>
+        <p>Welcome! Explore the docs using the sidebar or start here:</p>
+        <p>
+          <Link className="button button--primary" to="/accordproject">
+            Go to Overview
+          </Link>
+        </p>
+      </main>
+    </Layout>
+  );
+}
+
+

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

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 {

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

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 {

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