Docs site

.github/workflows/site-deploy.yml

@@ -0,0 +1,38 @@
+name: GH Page Deploy
+
+on:
+    push:
+        branches:
+            - main
+
+defaults:
+    run:
+        working-directory: ./site
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+
+        permissions:
+            contents: write
+            packages: read
+
+        steps:
+            - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+            - name: Use Node.js
+              uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
+              with:
+                  node-version: '22.x'
+                  registry-url: 'https://npm.pkg.github.com'
+                  scope: '@morganstanley'
+            - run: npm ci
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+            - run: npm run build
+            - name: Deploy
+              uses: crazy-max/ghaction-github-pages@fbf0a4fa4e00f45accd6cf3232368436ec06ed59 # v4.1.0
+              with:
+                  target_branch: gh-pages
+                  build_dir: docs
+              env:
+                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/site-pr-build.yml

@@ -0,0 +1,31 @@
+name: GH Page PR Build
+
+on:
+    pull_request:
+        branches:
+            - main
+
+defaults:
+    run:
+        working-directory: ./site
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+
+        permissions:
+            contents: read
+            packages: read
+
+        steps:
+            - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+            - name: Use Node.js
+              uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
+              with:
+                  node-version: '22.x'
+                  registry-url: 'https://npm.pkg.github.com'
+                  scope: '@morganstanley'
+            - run: npm ci
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+            - run: npm run build

eslint.config.mjs

@@ -32,6 +32,7 @@ const ignores = globalIgnores(
         : [
             '**/dist/**/*',
             '**/docs/**/*',
+            '**/site/**/*',
             '**/node_modules/**/*',
             ...(additionalIgnorePatterns != null ? additionalIgnorePatterns.split(',') : []),
         ],

site/.gitignore

@@ -0,0 +1,69 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Typescript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# dotenv environment variable files
+.env*
+
+# gatsby files
+.cache/
+public
+
+# Mac files
+.DS_Store
+
+# Yarn
+yarn-error.log
+.pnp/
+.pnp.js
+# Yarn Integrity file
+.yarn-integrity

site/.prettierignore

@@ -0,0 +1,4 @@
+.cache
+package.json
+package-lock.json
+public

site/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "endOfLine": "lf",
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5"
+}

site/README.md

@@ -0,0 +1,69 @@
+# Morgan Stanley GitHub Pages Documentation Gatsby Theme
+
+## Creating a documentation site for your project
+
+### Prerequisites
+
+Ensure that the appropriate version of `node` and `npm` is available in your workspace. Please refer to the `engines` attribute of the `package.json` for the current expected version.
+
+### Personal Access Token for GitHub Packages
+
+The theme that builds the branded documentation site is a private package. To build the site locally, you will need to generate a personal access token and add it to your `.npmrc`.
+
+```
+//npm.pkg.github.com/:_authToken=ghp_<token goes here>
+@morganstanley:registry=https://npm.pkg.github.com/
+```
+
+[Authenticating to GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-to-github-packages)
+
+### Template starter site
+
+Copy and paste the `site/` directory of the `ms-gh-pages` project into the root of your project then update the `siteMetadata` key in the `gatsby-config.js` file to match your project's information.
+
+```json
+siteMetadata: {
+    title: `Project GitHub Pages Template`, // your project's name
+    description: `Morgan Stanley Open Source Software`, // your project's description
+    siteUrl: `http://opensource.morganstanley.com`, // your project's url
+}
+```
+
+### Development Preview Server
+
+Go to http://localhost:8000 for the development preview of the website.
+
+```shell
+cd site
+npm install
+npm run start
+```
+
+### Update the Content
+
+Update the appropriate files located in the `site/content` directory with documentation for your project. For instance, to change the homepage text, update the `site/content/index.mdx`. Please be sure to _replace the content of each file in at least `/index.mdx` and `/documentation`_ to ensure a consistent experience across the Firm's Open Source projects.
+
+```
+/
+--/site
+----/content
+------/architecture - directory linked in header navigation
+--------index.mdx -> architecture landing page
+------/documentation - directory linked in header navigation
+--------index.mdx -> documentation landing page
+------index.mdx -> Site Homepage
+```
+
+### Dependabot
+
+The Morgan Stanley GitHub page documentation theme is a package that can be updated via Dependabot. Because its a private package, Dependabot will need to be given permission through a token. Update your project's `.github/dependabot.yml` with:
+
+```yaml
+registries:
+  npm-ghp:
+    type: npm-registry
+    url: 'https://npm.pkg.github.com'
+    token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Please refer to the [Dependabot Documentation](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot).

site/content/architecture/adr-001-use-adrs.mdx

@@ -0,0 +1,73 @@
+---
+type: ADR
+id: adr-001
+status: Accepted
+scope: global
+deciders: github group
+date: 2021-06-01
+title: Use ADRs
+---
+
+{/* Morgan Stanley makes this available to you under the Apache License, Version 2.0 (the "License"). You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0. See the NOTICE file distributed with this work for additional information regarding copyright ownership. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. */}
+
+### Context
+
+ComposeUI has several very explicit goals that make the practice and
+discipline of architecture very important:
+
+- We want to think deeply about all our architectural decisions,
+  exploring all alternatives and making a careful, considered,
+  well-researched choice.
+- We want to be as transparent as possible in our decision-making
+  process.
+- We don't want decisions to be made unilaterally in a
+  vacuum. Specifically, we want to give our steering group the
+  opportunity to review every major decision.
+- Despite being a geographically and temporally distributed team, we
+  want our contributors to have a strong shared understanding of the
+  technical rationale behind decisions.
+- We want to be able to revisit prior decisions to determine fairly if
+  they still make sense, and if the motivating circumstances or
+  conditions have changed.
+
+### Decision
+
+We will document every architecture-level decision for ComposeUI and its
+core modules with an
+[Architecture Decision Record](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). These
+are a well structured, relatively lightweight way to capture
+architectural proposals. They can serve as an artifact for discussion,
+and remain as an enduring record of the context and motivation of past
+decisions.
+
+The workflow will be:
+
+1. A developer creates an ADR document outlining an approach for a
+   particular question or problem. The ADR has an initial status of "proposed."
+2. The developers and steering group discuss the ADR. During this
+   period, the ADR should be updated to reflect additional context,
+   concerns raised, and proposed changes.
+3. Once consensus is reached, ADR can be transitioned to either an
+   "accepted" or "rejected" state.
+4. Only after an ADR is accepted should implementing code be committed
+   to the main branch of the relevant project/module.
+5. If a decision is revisited and a different conclusion is reached, a
+   new ADR should be created documenting the context and rationale for
+   the change. The new ADR should reference the old one, and once the
+   new one is accepted, the old one should (in its "status" section)
+   be updated to point to the new one. The old ADR should not be
+   removed or otherwise modified except for the annotation pointing to
+   the new ADR.
+
+### Consequences
+
+1. Developers must write an ADR and submit it for review before
+   selecting an approach to any architectural decision -- that is, any
+   decision that affects the way ComposeUI or a ComposeUI application is
+   put together at a high level.
+2. We will have a concrete artifact around which to focus discussion,
+   before finalizing decisions.
+3. If we follow the process, decisions will be made deliberately, as a group.
+4. The main branch of our repositories will reflect the high-level
+   consensus of the steering group.
+5. We will have a useful persistent record of why the system is the way it is.

site/content/architecture/index.mdx

@@ -0,0 +1,10 @@
+---
+title: Architecture Decision Records
+order: 0
+---
+
+<Hero title="Architecture Decision Records">
+  Directory of Architecture Decision Records (ADRs) for Morgan Stanley Open
+  Source projects.
+</Hero>
+<Toc directory="architecture" />