Adds documentation and automation for ref docs

.github/workflows/pages.yml

@@ -29,6 +29,11 @@ jobs:
         uses: actions/checkout@v3
       - name: Setup Pages
         uses: actions/configure-pages@v2
+      - name: Install SpectaQL
+        run: npm install -g spectaql@v2
+      - name: Build reference docs
+        run: |
+          spectaql --introspection-url https://timdex-api-prod-v2.herokuapp.com/graphql -e -t ./docs/reference docs/reference/_spectaql_config.yml
       - name: Build with Jekyll
         uses: actions/jekyll-build-pages@v1
         with:

.gitignore

@@ -34,6 +34,12 @@
 .solargraph.yml
 .vscode
 
+# Docs site ignores
 _site
 .jekyll-cache
 .jekyll-metadata
+
+# Docs site reference docs ignores
+/docs/reference/javascripts/
+/docs/reference/stylesheets/
+/docs/reference/index.html

README.md

@@ -55,10 +55,21 @@ bundle exec jekyll serve --incremental --source ./docs
 
 Once the jekyll server is running, you can access the local docs at http://localhost:4000
 
-### Automatic generation from openapi specification
+### Automatic generation of technical specifications from GraphQL
+
+Our GitHub Actions documentation build includes a step that uses [SpectaQL](https://github.com/anvilco/spectaql) to
+generate technical documentation from our GraphQL spec.
+
+You can generate this locally by installing SpectaQL and generating the html. See `Install SpectaQL` and
+`Build reference docs` in `./.github/workflows/pages.yml` for details on this process.
+
+Note: These files are intentionally excluded from version control to ensure the output generated via the Actions step is
+considered authoritative.
+
+The config file `./docs/reference/_spectaql_config.yml` controls the build process for this portion of our documentation
+and making changes to this file (which is included in version control) would be the main reason to run the process
+locally.
 
-We are using Swagger UI to automatically generate documentation from the `openapi.json` file in GitHub Pages. The HTML
-file is in `docs/index.html` and the `openapi.json` file always pulls from the `main` branch.
 ## Required Environment Variables (all ENVs)
 
 - `EMAIL_FROM`: email address to send message from, including the registration

docs/_config.yml

@@ -11,5 +11,10 @@ color_scheme: dark
 exclude:
   - architecture-decisions
 
+nav_external_links:
+  - title: Reference Docs
+    url: ./reference
+    hide_icon: false # set to true to hide the external link icon - defaults to false
+
 mermaid:
   version: "9.3.0"

docs/reference/_spectaql_config.yml

@@ -0,0 +1,37 @@
+spectaql:
+  # logoFile: ./assets/images/tim-timdex.svg
+  # faviconFile: ./test/fixtures/favicon.png
+  displayAllServers: true
+
+introspection:
+  # removeTrailingPeriodFromDescriptions: false
+  # schemaFile: ./examples/data/schema.gql
+  # metadataFile: ./examples/data/metadata.json
+  # dynamicExamplesProcessingModule: ./examples/customizations/examples
+  queryNameStrategy: capitalizeFirst
+  fieldExpansionDepth: 2
+
+  spectaqlDirective:
+    enable: true
+
+extensions:
+  graphqlScalarExamples: true
+
+info:
+  title: TIMDEX API Reference
+  description: Welcome to the TIMDEX API!
+  contact:
+    name: API Support
+    email: timdex@mit.edu
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+  x-introItems:
+    - title: TIMDEX Overview, Guides, and Tutorials
+      description: These reference docs are only part of our documentation. Please also see our [Guides and Tutorials](../).
+
+servers:
+  - url: https://timdex.mit.edu/graphql
+    description: Production
+    production: true
+