Merge pull request #71 from vauxia/feature/PGOV-563-Docs-framework

Docusarus POC

.ddev/config.yaml

@@ -14,6 +14,15 @@ composer_version: "2"
 web_environment:
   - DRUSH_ALLOW_XDEBUG=1
 corepack_enable: false
+web_extra_exposed_ports:
+  - name: "Documentation"
+    container_port: 4000
+    https_port: 4000
+    http_port: 4001
+web_extra_daemons:
+  - name: "docs"
+    command: "npm install && npm run start -- -h 0.0.0.0 -p 4000"
+    directory: /var/www/html/docs
 
 # Key features of DDEV's config.yaml:
 

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/docs/development/back-end/airtable.md

@@ -0,0 +1,48 @@
+# Airtable
+
+_Throughout the MVP development cycle_, the source of truth for all content on the
+site is in a protected [Airtable](https://airtable.com) base in the Performance
+Reporting workspace.
+
+## MVP Development and Migration
+
+When an MVP is finalized, a live version of the PGOV Drupal site will become
+the source of truth for finalized content and ongoing updates.
+
+Until then, the content team can populate, clean, and validate the information
+in Airtable, while the development team can make structural or architectural
+changes without needing to provide an upgrade path or support legacy data.
+
+It is possible to [bootstrap](../local) a fresh copy of the Drupal back end site
+and populate it with the latest content and files from Airtable.
+
+### Restricted Access
+
+Access to the Airtable base must be obtained in advance.
+
+### API Key
+
+[Local](../local) and live versions of the site be reinstalled and populated
+with content from Airtable, but depend on having a valid API key.
+
+An API key can be obtained at https://airtable.com/create/tokens
+
+The migration script expects to find the API key in an environment variable
+called `AIRTABLE_API_KEY`. When using DDEV, the new key can be added using an
+`.env` file:
+
+* Copy `.ddev/.env.pgov-example` to `.ddev/.env`
+* Add the new API key to the value of `AIRTABLE_API_KEY` in `.ddev/.env`
+* Run `ddev restart` for the settings to apply.
+
+### Data Migration
+
+PGOV content is migrated from Airtable using the [Migrate](https://www.drupal.org/docs/core-modules-and-themes/core-modules/migrate-module)
+framework built into Drupal core. A small module that extends some the core
+modules is in `web/modules/custom/pgov_migrate`. The module also contains
+preconfigured migrations and default content, which will be added to the site
+each time it's rebuilt.
+
+Migrations can be listed using `drush migrate:status` (this may take some time)
+Migrations can be executed using `ddev migrate` (local environment) or
+`bin/migrate` (hosted environment).

docs/docs/development/back-end/index.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 0
+title: Overview
+---
+# Drupal Back End

docs/docs/development/front-end/index.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 0
+title: Overview
+---
+# Next.js Front End

docs/cypress-tags.md → docs/docs/development/local/cypress.md

@@ -1,3 +1,8 @@
+---
+sidebar_position: 2
+title: Cypress
+---
+
 # Cypress tags available for grep
 
 The list below contains tags currently used in the Cypress tests. These are available as variables when using cypress-grep.
@@ -22,4 +27,4 @@ The list below contains tags currently used in the Cypress tests. These are avai
 
 ## Goal types
 - @apg
-- @strategic
+- @strategic

docs/docs/development/local/index.md

@@ -0,0 +1,54 @@
+---
+sidebar_position: 0
+---
+
+# Local Development
+
+
+This codebase is configured to use [DDEV](https://ddev.com/) to allow developers
+to run a version of the site locally, at the following URLs:
+
+| *URL*                              | *Purpose*
+|------------------------------------| ------------------
+| https://performance.ddev.site      | [Drupal back end](../back-end)
+| https://performance.ddev.site:3000 | [Next.js front end](../front-end)
+| https://performance.ddev.site:3999 | Documentation
+
+## DDEV
+
+Before setting up a local environment, refer to the
+[getting started](https://ddev.readthedocs.io/en/stable/) guide to prepare your
+computer to run this site using DDEV.
+
+Once DDEV is installed and working, you can use these commands in a terminal
+window to start local version of this site:
+
+```shell
+# Check out the site
+git clone [email protected]:CivicActions/pgov-cms.git
+
+# Enter the project directory
+cd pgov-cms
+
+# Start up the site
+ddev start
+```
+
+The site will now be available at the above URLs.
+
+## Site Database
+
+Throughout the MVP development process, the database is considered disposable.
+A new site can be bootstrapped from code and populated from a fresh migration:
+
+A migration requires access to the source bases ([more here](../back-end/airtable))
+With a proper access token in place, these commands will generate a fresh site,
+populated with content and images from Airtable.
+
+```shell
+# Bootstrap the site
+drush site-install --existing-config
+
+# Migrate content from Airtable
+ddev migrate
+```

docs/docs/intro.md

@@ -0,0 +1,7 @@
+---
+sidebar-position: 1
+slug: /
+title: PGOV Overview
+---
+# Technical documentation
+

docs/docusaurus.config.ts

@@ -0,0 +1,124 @@
+import {themes as prismThemes} from 'prism-react-renderer';
+import type {Config} from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
+const config: Config = {
+  title: 'Performance.gov',
+  tagline: 'Track the U.S. government\'s goals',
+  //favicon: 'img/favicon.ico',
+
+  // Set the production url of your site here
+  url: 'https://your-docusaurus-site.example.com',
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
+  baseUrl: '/',
+
+  // GitHub pages deployment config.
+  // If you aren't using GitHub pages, you don't need these.
+  organizationName: 'CivicActions', // Usually your GitHub org/user name.
+  projectName: 'pgov-cms', // Usually your repo name.
+
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+
+  // Even if you don't use internationalization, you can use this field to set
+  // useful metadata like html lang. For example, if your site is Chinese, you
+  // may want to replace "en" with "zh-Hans".
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          sidebarPath: './sidebars.ts',
+          // Please change this to your repo.
+          // Remove this to remove the "edit this page" links.
+          routeBasePath: '/',
+          editUrl:
+            'https://github.com/CivicActions/pgov-cms/tree/main/',
+        },
+        /** Will not use blog on this site.
+        blog: {
+          showReadingTime: true,
+          feedOptions: {
+            type: ['rss', 'atom'],
+            xslt: true,
+          },
+          // Please change this to your repo.
+          // Remove this to remove the "edit this page" links.
+          editUrl:
+            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
+          // Useful options to enforce blogging best practices
+          onInlineTags: 'warn',
+          onInlineAuthors: 'warn',
+          onUntruncatedBlogPosts: 'warn',
+        },
+         **/
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    // Replace with your project's social card
+    image: 'img/docusaurus-social-card.jpg',
+    navbar: {
+      title: 'PGOV DOCS ',
+      logo: {
+        alt: 'Performance.gov',
+        src: 'img/docusaurus.png',
+      },
+      items: [
+        {
+          type: 'docSidebar',
+          sidebarId: 'docSidebar',
+          position: 'left',
+          label: 'Docs',
+        },
+        {
+          href: 'https://github.com/CivicActions/pgov-cms',
+          label: 'GitHub',
+          position: 'right',
+        },
+      ],
+    },
+    footer: {
+      style: 'dark',
+      links: [
+        {
+          title: 'Docs',
+          items: [
+            {
+              label: 'Overview',
+              to: '/docs/',
+            },
+          ],
+        },
+        {
+          title: 'More',
+          items: [
+            {
+              label: 'GitHub',
+              href: 'https://github.com/CivicActions/pgov-cms',
+            },
+          ],
+        },
+      ],
+      copyright: `Copyright © ${new Date().getFullYear()} Performance.gov`,
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;