Main

.github/workflows/build.yml

@@ -2,9 +2,9 @@ name: Build
 
 on:
   push:
-    branches: [ '*' ]
+    branches: ["*"]
   pull_request:
-    branches: [ '*' ]
+    branches: ["*"]
 
 jobs:
   test:
@@ -15,28 +15,28 @@ jobs:
         ruby-version: [2.3, 2.4, 2.5, 2.6]
 
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby-version }}
-
-    - uses: actions/cache@v2
-      with:
-        path: vendor/bundle
-        key: gems-${{ runner.os }}-${{ matrix.ruby-version }}-${{ hashFiles('**/Gemfile.lock') }}
-        restore-keys: |
-          gems-${{ runner.os }}-${{ matrix.ruby-version }}-
-          gems-${{ runner.os }}-
-
-    # necessary to get ruby 2.3 to work nicely with bundler vendor/bundle cache
-    # can remove once ruby 2.3 is no longer supported
-    - run: gem update --system 3.3.27
-
-    - run: bundle config set deployment 'true'
-    - name: bundle install
-      run: |
-        bundle config path vendor/bundle
-        bundle install --jobs 4 --retry 3
-
-    - run: bundle exec middleman build
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+
+      - uses: actions/cache@v3
+        with:
+          path: vendor/bundle
+          key: gems-${{ runner.os }}-${{ matrix.ruby-version }}-${{ hashFiles('**/Gemfile.lock') }}
+          restore-keys: |
+            gems-${{ runner.os }}-${{ matrix.ruby-version }}-
+            gems-${{ runner.os }}-
+
+      # necessary to get ruby 2.3 to work nicely with bundler vendor/bundle cache
+      # can remove once ruby 2.3 is no longer supported
+      - run: gem update --system 3.3.27
+
+      - run: bundle config set deployment 'true'
+      - name: bundle install
+        run: |
+          bundle config path vendor/bundle
+          bundle install --jobs 4 --retry 3
+
+      - run: bundle exec middleman build

.github/workflows/deploy.yml

@@ -2,7 +2,7 @@ name: Deploy
 
 on:
   push:
-    branches: [ 'main' ]
+    branches: ["main"]
 
 jobs:
   deploy:
@@ -11,31 +11,31 @@ jobs:
       ruby-version: 2.5
 
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ env.ruby-version }}
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ env.ruby-version }}
 
-    - uses: actions/cache@v2
-      with:
-        path: vendor/bundle
-        key: gems-${{ runner.os }}-${{ matrix.ruby-version }}-${{ hashFiles('**/Gemfile.lock') }}
-        restore-keys: |
-          gems-${{ runner.os }}-${{ matrix.ruby-version }}-
-          gems-${{ runner.os }}-
+      - uses: actions/cache@v3
+        with:
+          path: vendor/bundle
+          key: gems-${{ runner.os }}-${{ matrix.ruby-version }}-${{ hashFiles('**/Gemfile.lock') }}
+          restore-keys: |
+            gems-${{ runner.os }}-${{ matrix.ruby-version }}-
+            gems-${{ runner.os }}-
 
-    - run: bundle config set deployment 'true'
-    - name: bundle install
-      run: |
-        bundle config path vendor/bundle
-        bundle install --jobs 4 --retry 3
+      - run: bundle config set deployment 'true'
+      - name: bundle install
+        run: |
+          bundle config path vendor/bundle
+          bundle install --jobs 4 --retry 3
 
-    - run: bundle exec middleman build
+      - run: bundle exec middleman build
 
-    - name: Deploy
-      uses: peaceiris/actions-gh-pages@v3
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./build
-        keep_files: true
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./build
+          keep_files: true

.github/workflows/dev_deploy.yml

@@ -2,7 +2,7 @@ name: Dev Deploy
 
 on:
   push:
-    branches: [ 'dev' ]
+    branches: ["dev"]
 
 jobs:
   deploy:
@@ -11,32 +11,32 @@ jobs:
       ruby-version: 2.5
 
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ env.ruby-version }}
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ env.ruby-version }}
 
-    - uses: actions/cache@v2
-      with:
-        path: vendor/bundle
-        key: gems-${{ runner.os }}-${{ matrix.ruby-version }}-${{ hashFiles('**/Gemfile.lock') }}
-        restore-keys: |
-          gems-${{ runner.os }}-${{ matrix.ruby-version }}-
-          gems-${{ runner.os }}-
+      - uses: actions/cache@v3
+        with:
+          path: vendor/bundle
+          key: gems-${{ runner.os }}-${{ matrix.ruby-version }}-${{ hashFiles('**/Gemfile.lock') }}
+          restore-keys: |
+            gems-${{ runner.os }}-${{ matrix.ruby-version }}-
+            gems-${{ runner.os }}-
 
-    - run: bundle config set deployment 'true'
-    - name: bundle install
-      run: |
-        bundle config path vendor/bundle
-        bundle install --jobs 4 --retry 3
+      - run: bundle config set deployment 'true'
+      - name: bundle install
+        run: |
+          bundle config path vendor/bundle
+          bundle install --jobs 4 --retry 3
 
-    - run: bundle exec middleman build
+      - run: bundle exec middleman build
 
-    - name: Deploy
-      uses: peaceiris/actions-gh-pages@v3.7.0-8
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        destination_dir: dev
-        publish_dir: ./build
-        keep_files: true
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3.7.0-8
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          destination_dir: dev
+          publish_dir: ./build
+          keep_files: true

README.md

@@ -1,3 +1,35 @@
+# DataScope API Documentation
+
+Public API reference for DataScope, published at **https://dscope.github.io/docs/**.
+
+All the content lives in one file: [`source/index.html.md`](source/index.html.md). The site is built with Slate, whose original README follows below.
+
+## Open your pull requests against `main`, not `master`
+
+This repository keeps two long-lived branches, and the defaults work against you:
+
+| Branch | Role |
+| --- | --- |
+| **`main`** | **The branch the site is built from.** `.github/workflows/deploy.yml` triggers on pushes here and publishes to `gh-pages` |
+| `master` | GitHub's configured default branch, so a new pull request targets it automatically. Nothing merged here reaches the live site |
+
+Because `master` is the default, a pull request opened without changing the base lands on the branch that does not publish. That is exactly how the two drifted: documentation accumulated on both sides for months, and each ended up missing endpoints the other had.
+
+**Set the base branch to `main` when you open a pull request.** If you already opened one against `master`, you can retarget it from the PR page without losing the review.
+
+The two branches were reconciled in July 2026, porting to `main` everything that existed only on `master`. If you find documentation present on one branch and absent from the other, they have drifted again and need another pass.
+
+### Working on the docs
+
+```bash
+bundle install
+bundle exec middleman server   # http://localhost:4567
+```
+
+The build runs on Ruby 2.3 to 2.6 in CI. Newer Rubies will not install the pinned dependencies.
+
+---
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/lord/img/master/logo-slate.png" alt="Slate: API Documentation Generator" width="226">
   <br>