Add versioned documentation and backfill docs for v3, v4 (rjsf-team#3774

)
heath-freenome · Jul 17, 2023 · c0265bd · c0265bd
1 parent 0e15118
commit c0265bd
Show file tree

Hide file tree

Showing 65 changed files with 6,110 additions and 107 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -32,6 +32,7 @@ should change the heading of the (upcoming) version to include a major version b
 
 - Switched to using npm workspaces for the sub-package hierarchy
   - NOTE: Developers may need to run the `npm run refresh-node-modules` script first to get the build and tests to work correctly
+- Backfilled Docusaurus site with documentation for v3, v4
 
 # 5.10.0
 

diff --git a/packages/docs/docs/index.mdx → packages/docs/docs/00-introduction.mdx b/packages/docs/docs/index.mdx → packages/docs/docs/00-introduction.mdx
@@ -13,7 +13,7 @@ A simple [React](https://reactjs.org/) component capable of building HTML forms
 A [live playground](https://rjsf-team.github.io/react-jsonschema-form/) is hosted on GitHub Pages:
 
 <a target='_blank' href='https://rjsf-team.github.io/react-jsonschema-form/'>
-  <img alt='Playground' src='https://i.imgur.com/M8ZCES5.gif' />
+    <img alt='Playground' src='https://i.imgur.com/M8ZCES5.gif'/>
 </a>
 
 ## Philosophy
@@ -118,9 +118,32 @@ Apache 2
 
 ## Credits
 
-| ![mozilla-services-logo](https://avatars1.githubusercontent.com/u/1066228?s=200&v=4)                 | ![browserstack logo](https://user-images.githubusercontent.com/1689183/51487090-4ea04f80-1d57-11e9-9a91-79b7ef8d2013.png) | ![netlify logo](https://www.netlify.com/img/global/badges/netlify-color-accent.svg) |
-| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| This project initially started as a [mozilla-services](https://github.com/mozilla-services) project. | Testing is powered by [BrowserStack](https://www.browserstack.com/).                                                      | Deploy Previews are provided by [Netlify](https://www.netlify.com).                 |
+<table>
+    <tr>
+        <th>
+            <img src="https://avatars1.githubusercontent.com/u/1066228?s=200&v=4" alt="mozilla-services-logo" style={{maxHeight: '100px'}} />
+        </th>
+        <td>
+            This project initially started as a <a href="https://github.com/mozilla-services">mozilla-services</a> project.
+        </td>
+    </tr>
+    <tr>
+        <th>
+            <img src="https://user-images.githubusercontent.com/1689183/51487090-4ea04f80-1d57-11e9-9a91-79b7ef8d2013.png" alt='browserstack logo'  style={{maxHeight: '100px'}}/>
+        </th>
+        <td>
+            Testing is powered by <a href="https://www.browserstack.com/" >BrowserStack</a>.
+        </td>
+    </tr>
+    <tr>
+        <th>
+            <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt='netlify logo'  style={{maxHeight: '100px'}}/>
+        </th>
+        <td>
+            Deploy Previews are provided by <a href="https://www.netlify.com">Netlify</a>.
+        </td>
+    </tr>
+</table>
 
 ## Who uses react-jsonschema-form?
 

diff --git a/packages/docs/docs/quickstart.md → packages/docs/docs/01-quickstart.md b/packages/docs/docs/quickstart.md → packages/docs/docs/01-quickstart.md
@@ -41,7 +41,7 @@ const schema: RJSFSchema = {
 render(<Form schema={schema} validator={validator} />, document.getElementById('app'));
 ```
 
-For more information and examples of JSON Schema properties that this library supports, see [Using JSON Schema](./usage/single.md).
+For more information and examples of JSON Schema properties that this library supports, see [Using JSON Schema](json-schema/single.md).
 
 ## Form uiSchema
 

diff --git a/packages/docs/docs/advanced-customization/custom-templates.md b/packages/docs/docs/advanced-customization/custom-templates.md
@@ -48,7 +48,7 @@ Below is the table that lists all the `templates`, their props interface, their
 You can use an `ArrayFieldTemplate` to customize how your arrays are rendered.
 This allows you to customize your array, and each element in the array.
 If you only want to customize how the array's title, description or how the array items are presented, you may want to consider providing your own [ArrayFieldDescriptionTemplate](#arrayfielddescriptiontemplate), [ArrayFieldItemTemplate](#arrayfielditemtemplate) and/or [ArrayFieldTitleTemplate](#arrayfieldtitletemplate) instead.
-You can also customize arrays by specifying a widget in the relevant `ui:widget` schema, more details over on [Custom Widgets](../usage/arrays.md#custom-widgets).
+You can also customize arrays by specifying a widget in the relevant `ui:widget` schema, more details over on [Custom Widgets](../json-schema/arrays.md#custom-widgets).
 
 ```tsx
 import { ArrayFieldTemplateProps, RJSFSchema } from '@rjsf/utils';
@@ -369,11 +369,12 @@ import { BaseInputTemplateProps } from '@rjsf/utils';
 import { getDefaultRegistry } from '@rjsf/core';
 import { Templates } from '@rjsf/mui';
 
-const { templates: { BaseInputTemplate } } = getDefaultRegistry();  // To get templates from core
+const {
+  templates: { BaseInputTemplate },
+} = getDefaultRegistry(); // To get templates from core
 // const { BaseInputTemplate } = Templates; // To get templates from a theme do this
 
-function MyBaseInputTemplate(props: BaseInputTemplateProps)
-{
+function MyBaseInputTemplate(props: BaseInputTemplateProps) {
   const customProps = {};
   // get your custom props from where you need to
   return <BaseInputTemplate {...props} {...customProps} />;

diff --git a/packages/docs/docs/advanced-customization/custom-widgets-fields.md b/packages/docs/docs/advanced-customization/custom-widgets-fields.md
@@ -329,7 +329,7 @@ The `registry` is an object containing the registered core, theme and custom fie
 
 - `fields`: The set of all fields used by the `Form`. Includes fields from `core`, theme-specific fields and any [custom registered fields](#custom-field-components);
 - `widgets`: The set of all widgets used by the `Form`. Includes widgets from `core`, theme-specific widgets and any [custom registered widgets](#custom-component-registration), if any;
-- `rootSchema`: The root schema, as passed to the `Form`, which can contain referenced [definitions](../usage/definitions.md);
+- `rootSchema`: The root schema, as passed to the `Form`, which can contain referenced [definitions](../json-schema/definitions.md);
 - `formContext`: The [formContext](../api-reference/form-props.md#formcontext) that was passed to `Form`;
 - `schemaUtils`: The current implementation of the `SchemaUtilsType` (from `@rjsf/utils`) in use by the `Form`. Used to call any of the validation-schema-based utility functions.
 

diff --git a/packages/docs/docs/advanced-customization/index.mdx b/packages/docs/docs/advanced-customization/index.mdx
@@ -0,0 +1,11 @@
+---
+title: Advanced Customization
+description: Advanced customization documentation for react-jsonschema-form.
+
+---
+
+import DocCardList from '@theme/DocCardList';
+
+<p>{frontMatter.description}</p>
+
+<DocCardList  />
diff --git a/packages/docs/docs/advanced-customization/internals.md b/packages/docs/docs/advanced-customization/internals.md
@@ -14,15 +14,15 @@ This component follows [JSON Schema](http://json-schema.org/documentation.html)
 
   The `anyOf` and `oneOf` keywords are supported; however, properties declared inside the `anyOf/oneOf` should not overlap with properties "outside" of the `anyOf/oneOf`.
 
-  You can also use `oneOf` with [schema dependencies](../usage/dependencies.md#schema-dependencies) to dynamically add schema properties based on input data.
+  You can also use `oneOf` with [schema dependencies](../json-schema/dependencies.md#schema-dependencies) to dynamically add schema properties based on input data.
 
   The `allOf` keyword is supported; it uses [json-schema-merge-allof](https://github.com/mokkabonna/json-schema-merge-allof) to merge subschemas to render the final combined schema in the form. When these subschemas are incompatible, though (or if the library has an error merging it), the `allOf` keyword is dropped from the schema.
 
-- `"additionalProperties":false` produces incorrect schemas when used with [schema dependencies](../usage/dependencies.md#schema-dependencies). This library does not remove extra properties, which causes validation to fail. It is recommended to avoid setting `"additionalProperties":false` when you use schema dependencies. See [#848](https://github.com/rjsf-team/react-jsonschema-form/issues/848) [#902](https://github.com/rjsf-team/react-jsonschema-form/issues/902) [#992](https://github.com/rjsf-team/react-jsonschema-form/issues/992)
+- `"additionalProperties":false` produces incorrect schemas when used with [schema dependencies](../json-schema/dependencies.md#schema-dependencies). This library does not remove extra properties, which causes validation to fail. It is recommended to avoid setting `"additionalProperties":false` when you use schema dependencies. See [#848](https://github.com/rjsf-team/react-jsonschema-form/issues/848) [#902](https://github.com/rjsf-team/react-jsonschema-form/issues/902) [#992](https://github.com/rjsf-team/react-jsonschema-form/issues/992)
 
 ## Handling of schema defaults
 
-This library automatically fills default values defined in the [JSON Schema](http://json-schema.org/documentation.html) as initial values in your form. This also works for complex structures in the schema. If a field has a default defined, it should always appear as default value in form. This also works when using [schema dependencies](../usage/dependencies.md#schema-dependencies).
+This library automatically fills default values defined in the [JSON Schema](http://json-schema.org/documentation.html) as initial values in your form. This also works for complex structures in the schema. If a field has a default defined, it should always appear as default value in form. This also works when using [schema dependencies](../json-schema/dependencies.md#schema-dependencies).
 
 Since there is a complex interaction between any supplied original form data and any injected defaults, this library tries to do the injection in a way which keeps the original intention of the original form data.
 

diff --git a/packages/docs/docs/api-reference/index.mdx b/packages/docs/docs/api-reference/index.mdx
@@ -0,0 +1,10 @@
+---
+title: API Reference
+description: API documentation for react-jsonschema-form.
+---
+
+import DocCardList from '@theme/DocCardList';
+
+<p>{frontMatter.description}</p>
+
+<DocCardList  />
diff --git a/packages/docs/docs/api-reference/uiSchema.md b/packages/docs/docs/api-reference/uiSchema.md
@@ -100,7 +100,7 @@ The `ui:options` property cannot be nested inside itself and thus is the last ex
 
 All the properties that follow can be specified in the `uiSchema` in either of the two equivalent ways.
 
-NOTE: The properties specific to array items can be found [here](../usage/arrays.md#array-item-uiSchema-options)
+NOTE: The properties specific to array items can be found [here](../json-schema/arrays.md#array-item-uiSchema-options)
 
 ### widget
 
@@ -324,7 +324,7 @@ render(<Form schema={schema} uiSchema={uiSchema} validator={validator} />, docum
 
 ### order
 
-This property allows you to reorder the properties that are shown for a particular object. See [Objects](../usage/objects.md) for more information.
+This property allows you to reorder the properties that are shown for a particular object. See [Objects](../json-schema/objects.md) for more information.
 
 ### placeholder
 

diff --git a/packages/docs/docs/usage/arrays.md → packages/docs/docs/json-schema/arrays.md b/packages/docs/docs/usage/arrays.md → packages/docs/docs/json-schema/arrays.md
diff --git a/packages/docs/docs/usage/definitions.md → ...ages/docs/docs/json-schema/definitions.md b/packages/docs/docs/usage/definitions.md → ...ages/docs/docs/json-schema/definitions.md
diff --git a/packages/docs/docs/usage/dependencies.md → ...ges/docs/docs/json-schema/dependencies.md b/packages/docs/docs/usage/dependencies.md → ...ges/docs/docs/json-schema/dependencies.md
diff --git a/packages/docs/docs/json-schema/index.mdx b/packages/docs/docs/json-schema/index.mdx
@@ -0,0 +1,10 @@
+---
+title: JSON Schema
+description: Documentation for how to use JSON Schema constructs in react-jsonschema-form.,
+---
+
+import DocCardList from '@theme/DocCardList';
+
+<p>{frontMatter.description}</p>
+
+<DocCardList  />
diff --git a/packages/docs/docs/usage/objects.md → packages/docs/docs/json-schema/objects.md b/packages/docs/docs/usage/objects.md → packages/docs/docs/json-schema/objects.md
diff --git a/packages/docs/docs/usage/oneof.md → packages/docs/docs/json-schema/oneof.md b/packages/docs/docs/usage/oneof.md → packages/docs/docs/json-schema/oneof.md
diff --git a/packages/docs/docs/usage/single.md → packages/docs/docs/json-schema/single.md b/packages/docs/docs/usage/single.md → packages/docs/docs/json-schema/single.md
diff --git a/packages/docs/docs/migration-guides/index.mdx b/packages/docs/docs/migration-guides/index.mdx
@@ -0,0 +1,10 @@
+---
+title: Migration Guides
+description: Guides for upgrading to new major versions of react-jsonschema-form
+---
+
+import DocCardList from '@theme/DocCardList';
+
+<p>{frontMatter.description}</p>
+
+<DocCardList  />
diff --git a/packages/docs/docs/usage/index.mdx b/packages/docs/docs/usage/index.mdx
@@ -0,0 +1,11 @@
+---
+title: Usage and Customization
+description: How to use react-jsonschema-form and customize your form behavior and appearance.
+
+---
+
+import DocCardList from '@theme/DocCardList';
+
+<p>{frontMatter.description}</p>
+
+<DocCardList  />
diff --git a/packages/docs/docusaurus.config.js b/packages/docs/docusaurus.config.js
@@ -41,6 +41,21 @@ const config = {
           routeBasePath: '/',
           sidebarPath: require.resolve('./sidebars.js'),
           editUrl: 'https://github.com/rjsf-team/react-jsonschema-form/tree/main/packages/docs/',
+          lastVersion: 'current',
+          versions: {
+            'current': {
+              label: 'v5',
+              path: '',
+            },
+            '4.2.3': {
+              label: 'v4',
+              path: 'version-4.2.3',
+            },
+            '3.2.1': {
+              label: 'v3',
+              path: 'version-3.2.1',
+            },
+          },
         },
         blog: false,
         theme: {
@@ -57,10 +72,10 @@ const config = {
       // image: 'img/docusaurus-social-card.jpg',
       navbar: {
         title: 'react-jsonschema-form documentation',
-        // logo: {
-        //   alt: 'RJSF Logo',
-        //   src: 'img/logo.svg',
-        // },
+        logo: {
+          alt: 'RJSF Logo',
+          src: 'https://raw.githubusercontent.com/rjsf-team/react-jsonschema-form/59a8206e148474bea854bbb004f624143fbcbac8/packages/core/logo.png',
+        },
         items: [
           {
             type: 'doc',
@@ -70,22 +85,27 @@ const config = {
           },
           {
             type: 'doc',
-            docId: '/api-reference',
+            docId: 'api-reference/index',
             position: 'left',
             label: 'API Reference',
           },
           {
             type: 'doc',
-            docId: '/advanced-customization',
+            docId: 'advanced-customization/index',
             position: 'left',
             label: 'Advanced Customization',
           },
           {
             type: 'doc',
-            docId: '/migration-guides',
+            docId: 'migration-guides/index',
             position: 'left',
             label: 'Upgrade Guide',
           },
+          {
+            type: 'docsVersionDropdown',
+            position: 'right',
+            dropdownActiveClassDisabled: true,
+          },
           {
             href: 'https://rjsf-team.github.io/react-jsonschema-form',
             position: 'right',
@@ -145,11 +165,11 @@ const config = {
           from: '/react-jsonschema-form/docs/',
           to: '/',
         },
-        // We will need to tune `contextualSearch` and `searchParameters` to handle search for versioned docs
+        // We may need to tune `contextualSearch` and `searchParameters` to handle search for versioned docs
         // Optional: see doc section -- https://docusaurus.io/docs/search#contextual-search
         contextualSearch: true,
         // Optional: Algolia search parameters
-        searchParameters: {},
+        // searchParameters: {},
         // Optional: path for search page that enabled by default (`false` to disable it)
         searchPagePath: 'search',
       },

diff --git a/packages/docs/sidebars.js b/packages/docs/sidebars.js
@@ -15,89 +15,7 @@
 const sidebars = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
   docs: [
-    'intro',
-    'quickstart',
-    'contributing',
-    {
-      type: 'category',
-      label: 'JSON Schema',
-      link: {
-        description: 'Documentation for how to use JSON Schema constructs in react-jsonschema-form.',
-        type: 'generated-index',
-        title: 'JSON Schema',
-        slug: '/json-schema',
-      },
-      items: [
-        'usage/single',
-        'usage/objects',
-        'usage/arrays',
-        'usage/definitions',
-        'usage/dependencies',
-        'usage/oneof',
-      ],
-    },
-    {
-      type: 'category',
-      label: 'Usage',
-      link: {
-        type: 'generated-index',
-        title: 'Usage',
-        description: 'How to use react-jsonschema-form to customize your form behavior and appearance.',
-        slug: '/usage',
-      },
-      items: ['usage/widgets', 'usage/themes', 'usage/validation'],
-    },
-    {
-      type: 'category',
-      label: 'Advanced Customization',
-      link: {
-        type: 'generated-index',
-        title: 'Advanced Customization',
-        description: 'Advanced customization documentation for react-jsonschema-form.',
-        slug: '/advanced-customization',
-      },
-      items: [
-        'advanced-customization/custom-widgets-fields',
-        'advanced-customization/custom-templates',
-        'advanced-customization/custom-themes',
-        'advanced-customization/internals',
-        'advanced-customization/typescript',
-      ],
-    },
-    {
-      type: 'category',
-      label: 'API Reference',
-      link: {
-        type: 'generated-index',
-        title: 'API Reference',
-        description: 'API documentation for react-jsonschema-form.',
-        slug: '/api-reference',
-      },
-      items: [
-        'api-reference/uiSchema',
-        'api-reference/themes/semantic-ui/uiSchema',
-        'api-reference/themes/chakra-ui/uiSchema',
-        'api-reference/form-props',
-        'api-reference/utility-functions',
-        'api-reference/validator-ajv8'
-      ],
-    },
-    {
-      type: 'category',
-      label: 'Migration Guides',
-      link: {
-        type: 'generated-index',
-        title: 'Migration Guides',
-        description: 'Guides for upgrading to a major version of react-jsonschema-form.',
-        slug: '/migration-guides',
-      },
-      items: [
-        'migration-guides/v5.x upgrade guide',
-        'migration-guides/v4.x upgrade guide',
-        'migration-guides/v3.x upgrade guide',
-        'migration-guides/v2.x upgrade guide',
-      ],
-    },
+    {type: "autogenerated", dirName: '.'},
   ],
 };