developers.sparkpost.com

This repo contains the code and documentation that powers developers.sparkpost.com.

Get started

Requirements

To develop with this repository, you must have the following:

1. Node: version 14.16.1
2. npm: version 7 recommended (version 6 is incompatible with the current lock file)
3. A clone of this repo

Installing dependencies

1. cd developers.sparkpost.com to go into the website directory
2. Run npm run bootstrap to install the npm dependencies

Local development

When developing locally, you have two options: developing the whole website or develop just the API reference section. All content will hot-reload. If you aren't seeing changes, restart the development server.

Develop the website

This will develop the whole developer site.

1. Run npm run develop
2. Open http://localhost:4000/ to view the website.

Develop API reference

This is what you want if you are making documentation changes.

This will only develop the API reference pages and skip unnecessary queries.

1. Run npm run docs
2. Open http://localhost:4000/api/ to view the docs.

Develop Netlify Lambda Functions

To develop Netlify Functions locally, run npm run lambda. This will start a second development server for the serverless functions.

Each file located in the lambda/ directory will be deployed as a serverless function.

Contributing

You'll find the all the content, pages, and data inside the content folder. If you are contributing content, take a few minutes and read through the contributing guidelines.

Create a branch

Create a branch for your work in the repo:

1. git checkout main to checkout the main branch
2. git pull origin main to get the lastest code
3. git checkout -b your-branch-name to create a branch

Make your changes

1. Follow the Local development instructions to start the development server
2. Make your changes as needed
3. Changes to any files in the content and src directories will hot-reload.
4. If you make changes files in the plugins and gatsby directories or any top-level files, you will need to restart the server.

Push your changes

1. Stage and commit your changes (git add -A && git commit -m "Describe what you did")
2. Push your changes (git push origin your-branch-name)
3. Create a Pull Request against the main branch. Netlify will publish a deploy preview so you can share and preview your changes as a live site.

Troubleshooting

Python related issues

ModuleNotFoundError: No module named 'distutils' during npm run bootstrap

1. distutils package is removed in Python version 3.12
2. Create a virtual environment (venv) and pip install setuptools
3. or use a Python version 3.11 or earlier

M1 Pro related issues

fatal error: 'vips/vips8' file not found: during npm run bootstrap

1. You have to install "libvps" globally on your mac system to get this plugin to work on your development machine. You need brew installed to do this.
2. The "libvps" depends on gcc, so do:
3. brew install --build-from-source gcc
4. brew install vips
5. Proceed with npm run boostrap again

FATAL ERROR: wasm code commit Allocation failed - process out of memory during npm run docs

1. Install node v.16.14.0 (you can use nodenv or node-build for that)
2. Proceed with npm run docs again