Merge branch 'OneBusAway:main' into methodpagefix

README.md

@@ -6,6 +6,10 @@ Welcome to the GitHub project that powers the official [OneBusAway Developer Doc
 
 Want to help improve the documentation? Thank you! You can easily improve the official OneBusAway documentation by modifying the Markdown files that comprise it. We welcome any size of contribution, ranging from typos and corrected links, to brand-new tutorials.
 
+## Import Javadocs from OBA Sites
+
+From the root of the project, run the command `bin/update_javadocs` to see a list of available projects from which Javadocs can be imported.
+
 ## Develop New Features/Fix Bugs
 
 ### Prerequisites
@@ -94,7 +98,7 @@ The website built from this project is deployed automatically to a static hostin
 - For work in progress pull requests, please use the Draft PR feature.
 - Make sure all tests pass and add additional tests for the code you submit.
 - Document your reasoning behind the changes. Explain why you wrote the code in the way you did. The code should explain what it does.
-- If there's an existing issue, reference to it by adding something like `References/Closes/Fixes/Resolves #123`, where 123 is the issue number. 
+- If there's an existing issue, reference to it by adding something like `References/Closes/Fixes/Resolves #123`, where 123 is the issue number.
 - Please fill out the PR Template when making a PR.
 
 > Please note: maintainers may close your PR if it has gone stale or if we don't plan to merge the code.
@@ -118,7 +122,3 @@ This project exists because of all the people who have contributed.
 ## The bottom line
 
 We are all humans trying to work together to improve the community. Let's always be kind and appreciate the importance of making compromises. ❤️
-
-
-
-

bin/update_javadocs

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+
+require 'tmpdir'
+
+MODULES = {
+  "onebusaway-gtfs-modules" => (->{ build_gtfs_modules })
+}
+
+def build_gtfs_modules
+  repo_url = 'https://github.com/OneBusAway/onebusaway-gtfs-modules.git'
+  temp_dir = Dir.mktmpdir
+
+  begin
+    # Clone the repository into the temporary directory
+    system("git clone --single-branch --branch gh-pages #{repo_url} #{temp_dir}")
+
+    if $?.success?
+        puts "Repository cloned into temporary directory: #{temp_dir}"
+    else
+        puts "Failed to clone repository."
+        exit
+    end
+
+    archive_path = Dir.chdir(temp_dir) do |path|
+      archive_command = "git archive --format=zip -o gh-pages.zip HEAD"
+      system(archive_command)
+
+      archive_path = File.join(temp_dir, 'gh-pages.zip')
+
+      if $?.success?
+        puts "Archive created successfully: #{archive_path}"
+      else
+        puts "Failed to create archive."
+        exit
+      end
+      archive_path
+    end
+
+    system("unzip -o #{archive_path} -d ./src/modules/onebusaway-gtfs-modules/current")
+  ensure
+    # Clean up the temporary directory
+    FileUtils.remove_entry(temp_dir)
+  end
+end
+
+mod = ARGV[0]&.strip
+lam = MODULES[mod]
+
+if lam
+  lam.call
+else
+  puts "Unknown module: '#{mod}'"
+  puts "Call this script with one of the following options:"
+  MODULES.keys.each {|k| puts "    - #{k}"}
+  exit
+end

frontend/javascript/page_navigation.js

@@ -19,32 +19,9 @@ export function enableScrollToTop() {
 export function setupSidebar() {
   const h1Elements = document.querySelectorAll('h1');
   const h2Elements = document.querySelectorAll('article h2');
-  const sidebar = document.querySelector('.sidebar');
-
-  function appendSidebarItem(textContent, tagName) {
-    const newItem = document.createElement('a');
-    newItem.textContent = textContent;
-    if (tagName === 'h1') {
-      newItem.classList.add('sidebar-item', 'text-green-500');
-    }
-    else if (tagName === 'h2') {
-      newItem.classList.add('sidebar-item-h2', 'text-gray-500', 'hover:text-green-400', 'ml-4', 'cursor-pointer');
-    }
-    sidebar.appendChild(newItem);
 
-    newItem.addEventListener('click', function() {
-      const currentVersion = newItem.textContent;
-      const headings = document.querySelectorAll('h2');
-      let targetElement = null;
-      headings.forEach(function(heading) {
-        if (heading.textContent.trim() === currentVersion.trim()) {
-          targetElement = heading;
-        }
-      });
-      if (targetElement) {
-        window.scrollTo(0, targetElement.offsetTop - 100);
-      }
-    });
+  if (h2Elements.length == 0) {
+    return;
   }
 
   h1Elements.forEach(function (element) {
@@ -67,3 +44,30 @@ export function saveAndRestoreNavigationPosition() {
     console.log('clicked')
   });
 };
+
+function appendSidebarItem(textContent, tagName) {
+  const sidebar = document.querySelector('.sidebar');
+  const newItem = document.createElement('a');
+  newItem.textContent = textContent;
+  if (tagName === 'h1') {
+    newItem.classList.add('sidebar-item', 'text-green-500', 'block');
+  }
+  else if (tagName === 'h2') {
+    newItem.classList.add('sidebar-item-h2', 'text-gray-500', 'hover:text-green-400', 'ml-4', 'block', 'cursor-pointer');
+  }
+  sidebar.appendChild(newItem);
+
+  newItem.addEventListener('click', function() {
+    const currentVersion = newItem.textContent;
+    const headings = document.querySelectorAll('h2');
+    let targetElement = null;
+    headings.forEach(function(heading) {
+      if (heading.textContent.trim() === currentVersion.trim()) {
+        targetElement = heading;
+      }
+    });
+    if (targetElement) {
+      window.scrollTo(0, targetElement.offsetTop - 100);
+    }
+  });
+}

frontend/styles/index.css

@@ -24,6 +24,10 @@
 @tailwind base;
 @tailwind components;
 
+.prose h4 {
+  font-weight: 600;
+}
+
 button.DocSearch.DocSearch-Button {
   @apply h-8 w-full items-center gap-2 rounded-full bg-white pl-2 pr-3 text-sm text-zinc-500 ring-1 ring-zinc-900/10;
   @apply transition hover:ring-zinc-900/20 lg:flex dark:bg-white/5 dark:text-zinc-400 dark:ring-inset dark:ring-white/10 dark:hover:ring-white/20;
@@ -63,30 +67,28 @@ pre.highlight {
 }
 
 ::-webkit-scrollbar-track {
-  background-color : #686868;
+  @apply dark:bg-zinc-800 bg-[#f3f3f3];
 }
 
 ::-webkit-scrollbar-thumb {
-  background: #424242;
+  @apply dark:bg-zinc-600 bg-[#c2c2c2];
 }
 
 ::-webkit-scrollbar-thumb:hover {
-  background: #848484;
+  @apply dark:bg-zinc-400 bg-zinc-400;
 }
 
-@media (prefers-color-scheme: light) {
-    ::-webkit-scrollbar-track {
-      background-color: #f3f3f3;
-    }
-
-    ::-webkit-scrollbar-thumb {
-      background: #848484;
-    }
+::-webkit-scrollbar-thumb:active {
+  @apply dark:bg-zinc-200 bg-zinc-500;
+}
 
-    ::-webkit-scrollbar-thumb:hover {
-      background: #333;
-    }
+@tailwind utilities;
 
+/* Prevent headings from getting hidden when directly accessing sections with ids: */
+:target:before {
+    content: "";
+    display: block;
+    height: 80px;
+    margin-top: -80px; 
 }
 
-@tailwind utilities;

src/_layouts/default.erb

@@ -32,7 +32,7 @@
               </div>
             </article>
           </main>
-          <div class="hidden sidebar text-xs p-4 2xl:flex flex-col fixed top-24 right-12 w-fit max-w-72 h-fit"></div>
+          <div class="hidden md:block sidebar text-xs fixed top-24 right-6 w-fit max-w-60 h-fit"></div>
           <%= render "footer", locals: { metadata: site.metadata } %>
         </div>
       </div>

src/_partials/_navbar.erb

@@ -10,52 +10,39 @@
       children: {
         "Home" => '/',
         "About" => '/about',
+        "Features" => '/features',
         "Downloads" => '/downloads',
         "Getting Help" => '/getting-help',
-        "Release Notes" => '/release-notes'
+        # "Release Notes" => '/release-notes' # April 2024: wildly out of date. hiding until we can fix that.
       },
       current_path: resource.relative_url
     )) %>
 
     <%= render(NavigationSection.new(
       "Guides",
       children: {
-        "Ported Wiki Guides" => '/guides/ported-wiki-guides',
-        "Quickstart" => '/guides/quickstart-guide',
-        "Installation" => '/guides/installation-guide',
-        "Transit Data Bundle" => '/guides/transit-data-bundle-guide',
-        "Realtime Config" => '/guides/realtime-configuration-guide',
-        "API Config" => '/guides/api-webapp-configuration-guide',
-        "Phone (IVR) Config" => '/guides/phone-webapp-configuration-guide',
-        "Web Config" => '/guides/webapp-configuration-guide',
-        "Database Config" => '/guides/database-configuration-guide',
-        "Troubleshooting" => '/guides/troubleshooting-guide'
+        "Deployment" => '/guides/deployment',
+        "Outdated Guides" => '/guides/outdated'
       },
       current_path: resource.relative_url
     )) %>
 
     <%= render(NavigationSection.new(
-      "Features",
+      "Javadocs",
       children: {
-        "Web" => '/features/web',
-        "Phone and SMS" => '/features/phone-and-sms',
-        "Sign Mode" => '/features/sign-mode',
-        "GTFS Realtime" => '/features/gtfs-realtime',
-        "REST API" => '/api/where',
-        "Search API" => '/api/where/search',
+        "onebusaway-gtfs-modules" => '/modules/onebusaway-gtfs-modules/current/'
       },
       current_path: resource.relative_url
     )) %>
 
-    <%= render (NavigationSection.new(
-      "REST API Methods",
-      children: site.data.rest_api['methods'].reduce({}) {|acc, kv| k = kv.first; acc[k] = "/api/where/methods/#{k}"; acc },
-      current_path: resource.relative_url
-    )) %>
-
-    <%= render (NavigationSection.new(
-      "REST API Elements",
-      children: site.data.rest_api['elements'].reduce({}) {|acc, kv| k = kv.first; v = kv.last; acc[(v['name'] || k)] = "/api/where/elements/#{k}"; acc },
+    <%= render(NavigationSection.new(
+      "REST API",
+      children: {
+        "About the REST API" => '/api/where',
+        "API Methods" => '/api/where/methods',
+        "API Elements" => '/api/where/elements',
+        "Search" => '/api/where/search',
+      },
       current_path: resource.relative_url
     )) %>
   </ul>

src/api/where/elements/index.erb

@@ -0,0 +1,17 @@
+---
+layout: page
+title: REST API Elements
+---
+
+<ul>
+  <% site.data.rest_api['elements'].each do |k,v| %>
+    <li>
+      <a href="/api/where/elements/<%= k %>">
+        <%= v['name'] || k %>
+      </a>
+      <% if v['description'] %>
+        - <%= v['description'] %>
+      <% end %>
+    </li>
+  <% end %>
+</ul>

src/api/where/methods/index.erb

@@ -0,0 +1,17 @@
+---
+layout: page
+title: REST API Methods
+---
+
+<ul>
+  <% site.data.rest_api['methods'].each do |k,v| %>
+    <li>
+      <a href="/api/where/methods/<%= k %>">
+        <%= v['name'] || k %>
+      </a>
+      <% if v['description'] %>
+        - <%= v['description'] %>
+      <% end %>
+    </li>
+  <% end %>
+</ul>

src/features/index.md

@@ -0,0 +1,12 @@
+---
+layout: page
+title: Features
+---
+
+OneBusAway offers a rich set of features for transit agencies and end users.
+
+* [Web UI](/features/web)
+* [Phone and SMS](/features/phone-and-sms)
+* [Sign Mode](/features/sign-mode)
+* [GTFS Realtime](/features/gtfs-realtime)
+* [REST API](/api/where)

src/guides/deployment/index.erb

@@ -0,0 +1,35 @@
+---
+title: Deployment Guides
+layout: page
+---
+
+<p>
+  This page is the hub for all of our guides and frequently asked questions about
+  deploying OneBusAway for production use.
+</p>
+
+<p>
+  Over time, you can expect to find a variety of guides covering deployment to platforms like
+  Kubernetes, AWS, Google Cloud Platform, Microsoft Azure, and more. For now, if you would like
+  to help, check out our <a href="https://github.com/OneBusAway/onebusaway-docker/issues">onebusaway-docker issue tracker</a>
+  where this work is being coordinated.
+</p>
+
+<h2>Docker Images</h2>
+
+<p>
+  We maintain official OneBusAway Docker images on <a href='https://hub.docker.com/u/opentransitsoftwarefoundation'>Docker Hub</a>.
+  We strongly recommend using a versioned image instead of the `latest` tag. You can learn more about using the Docker images with
+  <a href="https://docs.docker.com/compose/">Docker Compose</a> in the <a href="https://github.com/OneBusAway/onebusaway-docker">onebusaway-docker project README</a>.
+</p>
+
+<h2>Render</h2>
+
+<p>
+  <a href='https://www.render.com'>Render.com</a> is a Platform as a Service (PaaS) provider that can be much easier to work with than AWS, GCP, or Azure while still
+  offering a rich and compelling set of services for creating, orchestrating, and maintaining software using Docker and Render's Infrastructure as Code (IaC) tooling.
+</p>
+
+<p>
+  <a href="/guides/deployment/render">Learn how to deploy OneBusAway on Render →</a>
+</p>