acf-quizbowl.com

This is the repository for the official ACF website. It is open-source, so any ACF member can contribute.

The static website is built using Jekyll, a Ruby Gem.

Setup

Ruby

• Install rbenv to manage Ruby versions on your device. You can also use chruby, but rbenv is recommended.

  • If you have a Mac or Linux machine, use the default rbenv and install ruby-build as well.
  • If you have a Windows machine, use rbenv-for-windows.

• Once rbenv is set up, install the latest version of Ruby (as of September 2024, the website runs on Ruby 3.4.5).

  • Mac / Linux:

    rbenv install -l # List latest stable versions
    rbenv install YOUR_CHOSEN_VERSION # Install the version of your choice from the list produced by the previous command
    

  • Windows:

    rbenv install head # Install the latest version
    

• Add Ruby and Gems to your path:

  • Mac / Linux:

    • Add the following to your .bashrc or .zshrc file:

      export GEM_HOME="$(ruby -e 'puts Gem.user_dir')"
      export PATH="$PATH:$GEM_HOME/bin"
      

  • Windows:

    • Add the following to your $profile (use > echo $profile in PowerShell to find where this is, it's usually Documents\PowerShell\Microsoft.PowerShell_profile.ps1):

      $env:RBENV_ROOT = "C:\Ruby-on-Windows"
      & "$env:RBENV_ROOT\rbenv\bin\rbenv.ps1" init
      

Jekyll

• Install Jekyll:

  $ gem install jekyll
  

• Install Bundler.

  $ gem install bundler
  

Run Locally

• Clone this repository.

• Enter the repository folder.

• Install all the Gems in the Gemfile:

  $ bundle install
  

• Run locally:

  $ bundle exec jekyll serve
  

Updating Members

The ACF membership tables are maintained using a Google Sheets spreadsheet as the source of truth, shared among ACF members. The data is synced to the website via a Python script that generates JSON, Excel, and updates the HTML tables.

Workflow for Updating Members

1. Update the Google Sheets spreadsheet with new/updated member data. The spreadsheet should have columns: Full Name, First Name, Last Name, Email, Status, Affiliations, Contributions, Skills, Last Activity. Affiliations and Contributions should be newline-separated in their cells.

2. If this is the first time you are running the script on your machine, follow the directions to add a service account key to your local copy of the repository.

3. Run the sync script to extract data from Google Sheets and update the website files:

   python3 scripts/sync_from_sheets.py [sheet_id] [--credentials credentials_file]

   This script:

   • Authenticates with Google Sheets using a service account.
   • Reads member data from the specified spreadsheet.
   • Generates about/members.json (JSON format).
   • Generates members.xlsx (Excel spreadsheet).
   • Updates the HTML tables in about/members.md.

   If no arguments are provided, it uses default values (sheet ID for ACF Master list and credentials file at scripts/credentials.json).

4. Confirm the updates by checking the generated files and running the Jekyll site locally to verify the changes.

Google Service Account

The script uses a Google Service Account (ACF Members Maintenance) for authentication.

Important

To run the script, you need to download a JSON key for the service account to the local copy of this repository on your machine. See the directions below for doing so.

• Name/ID: acf-members-maintenance
• Email: acf-members-maintenance@acf-members-maintenance.iam.gserviceaccount.com
• Project number: 1060389719532
• Credentials: /scripts/credentials.json
• Dashboard
• Cloud hub

This account has already been set up via the ACF Webmaster account, and you should not need to modify it for any reason. If for some reason you need to modify its settings or set up a new one in its place:

1. Create or access a Google Cloud Project with the Google Sheets API enabled.

2. Modify the existing service account or create a Service Account in the Google Cloud Console:

   • Go to IAM & Admin > Service Accounts.
   • Modify the existing service account or create a new service account with appropriate permissions (add access to the Google Sheets API).
   • Generate a JSON key for the service account. Call it credentials.json and save it in /scripts/.

3. Share the Google Sheet with the service account email (found in the JSON key file under client_email).

4. Place the JSON key file in the repository at scripts/credentials.json (or specify a different path with --credentials).

5. Install dependencies:

   pip install gspread google-auth openpyxl

The service account needs read access to the Google Sheet. Ensure the sheet is shared with the service account's email address.

Contributing

Create an issue to suggest a new feature/page or discuss errors on the website.

Please fork this repository and then create a PR to add more features. For more info, see GitHub's documentation.