Provides resources for developers using Nexmo API platforms
This repository is the content for https://developer.nexmo.com, which includes the Vonage documentation, API reference, SDKs, Tools & Community content. To get a Vonage account, sign up for free at nexmo.com.
We write the docs in US English and enforce this at build time with a CI check. You can run the check locally using the following command:
yarn spellcheck
Or if you're using Docker:
docker-compose exec web yarn spellcheck db:migrate
If there is a word that isn't in the dictionary but is correct to use, add it to the .spelling
file (there's a lot of exceptions in there, including Vonage
!)
We check our content for any offensive, ableist or gendered language and enforce this at build time with a CI check. You can run the check locally using the following command:
./node_modules/.bin/alex _documentation/en _partials _modals _tutorials
Or if you're using Docker:
docker-compose exec web ./node_modules/.bin/alex _documentation/en _partials _modals _tutorials
The project can be run on your laptop, either directly or using Docker. These instructions have been tested for Mac.
Install Homebrew
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Install required packages, create database and configure git
.
Note: A default database is created for you when you run the
db:setup
script. If you'd like to create and use a different database or user, usecreatedb database_name_here
orcreateuser username_here
and make sure your.env
file is updated accordingly (See .env.example).
brew install postgres rbenv git nvm redis
brew services start postgresql
brew services start redis
If you have not already, update git config with your name and email address.
git config --global user.name "NAME"
git config --global user.email "[email protected]"
Generate an SSH key for authentication
ssh-keygen -t rsa
cat .ssh/id_rsa.pub # Add to GitHub
Clone ADP to your local machine:
git clone [email protected]:Nexmo/nexmo-developer.git
cd nexmo-developer
Copy the contents of the example file: cp .env.example .env
and check if it worked by running cat .env
(it should produce an output)
Open the file: code .env
, find the redis line (probably line 35) and comment it out
Install the correct versions of ruby, as well as dependencies:
rbenv install 2.7.2
rbenv global 2.7.2
gem install bundle
bundle install
rbenv: commend not found
run brew update && brew update ruby-build
.ruby-build definition not found 2.7.2
, you need to update the xcode: xcode-select --install
rvm
: rvm --default use 2.7.2 && gem install bundle && bundle install
Set up access to submodules: git submodule init && git submodule update
and then git config --global submodule.recurse true
Start postgres: brew services start postgresql
and if that doesn't work brew services restart postgresql
.
PG::ConnectionBad - could not connect to server: Connection refused
, you can try installing the correct version or re-install postgres: brew uninstall postgresql && rm -rf /usr/local/bin/postgres && rm -rf .psql_history .psqlrc .psql.local .pgpass .psqlrc.local && brew update && brew install postgres
Start the local server:
OAS_PATH=“pwd/_open_api/api_specs/definitions” bundle exec nexmo-developer --docs=`pwd` --rake-ci
You should now be able to see the site on http://localhost:3000
If you don't want to install Ruby & PostgreSQL then you can use docker to sandbox the Vonage API Developer Portal into its own containers. After you Install Docker run the following:
$ git clone [email protected]:Nexmo/nexmo-developer.git
$ cd nexmo-developer
Set up access to submodules with the following two commands:
git submodule init && git submodule update
and then:
git config --global submodule.recurse true
There are two ways to run docker-compose.
$ docker-compose up
Once you can see the logs have booted the containers, open a new terminal window and proceed to running the migrations.
You can also run docker as a background process by adding the switch to run it as a daemon. To do this, first run the following:
$ docker-compose up -d
Now check that your containers have booted by running docker ps
. You should see the following two containers running:
nexmo-developer_web_1
nexmo-developer_db_1
Once you've confirmed that both containers are running, it's time to run the migrations.
docker-compose run web bundle exec rake db:migrate
At this point, open your browser to http://localhost:3000/ and you should see the homepage. The first time you click on Documentation
it might take 5 seconds or so, but any further page loads will be almost instantaneous.
To stop the server press ctrl+c
.
If you get an error that says "We're sorry, but something went wrong." you might need to run the database migrations with
docker-compose run web bundle exec rake db:migrate
You can access the admin dashboard by visiting /admin
. Initially, you will have an admin user with the username of [email protected]
and password of development
.
The following is an example if you are running the Vonage API Developer Portal within a Docker container:
docker exec -it <container_id> rake db:seed
New admin users can be created by visiting /admin/users
.
Some of the contents of ADP are brought in via git submodules, such as the OpenAPI Specification (OAS) documents. A submodule is a separate repository used within the main repository (in this case ADP) as a dependency. The main repository holds information about the location of the remote repository and which commit to reference. So to make a change within a submodule, you need to commit to the submodule and the main repository and crucially remember to push both sets of changes to GitHub.
Here are some tips for working with submodules:
git submodule init
git submodule update
git pull
git submodule update
Make sure you are inside the directory that is a submodule.
You are not done, keep reading! A second pull request is needed to update the main repo, including any other changes to that repo and an update to the submodule pointing to the new (merged) commit to use.
git pull
If you made changes on the repo outside of ADP, then you will need to come and make a commit on ADP to update which commit in the submodule the ADP repository is pointing to.
Make a branch, change into the submodule directory and git pull
or do whatever you need to do to get HEAD
pointing to the correct commit. In the top level of the project, add the change to the submodules file and commit and push. Then open the pull request as you would with any other changes.
Never git add .
this will make bad things happen with submodules. Try git add -p
instead. You're welcome.
If you're not sure what to do, ask for help. It's easier to lend a hand along the way than to rescue it later!
Git docs for submodules: https://git-scm.com/book/en/v2/Git-Tools-Submodules
A flow chart on surviving submodules from @lornajane: https://lornajane.net/posts/2016/surviving-git-submodules
Tutorials support a host of programming languages. The languages a tutorial supports is always displayed on the right hand side of the page.
It allows users to follow tutorials in the programming language of their choice (if available).
The list of supported languages can be found in the config/code_languages.yml
file.
This file can be expanded to support additional languages if they are not yet available.
NB: Icons for all languages can be found in the Station repository. You will need to upload one whenever you add a new language.
git pull
.$ docker-compose up --build
PG::ConnectionBad - could not connect to server: Connection refused
when I try to run the app.This error indicates that PostgreSQL is not running. If you installed PostgreSQL using brew
you can get information about how to start it by running:
$ brew info postgresql
Once PostgreSQL is running you'll need to create and migrate the database. See Setup for instructions.
docker rm -vf $(docker ps -a -q) THEN
docker rmi -f $(docker images -a -q)
Build: In your local repo folder run docker-compose up
. Wait until it completes without error.
Migration: In a separate terminal, same folder, run docker-compose run web bundle exec rake db:migrate
. Wait until it completes without error.
Test: In your browser open http://localhost:3000 and navigate to test for your changes in your local copy of your documentation.
Whenever new sections similar to _blog
, _changelogs
are added they may not be registered which leads to a broken page when selected from the navbar.
Check to see if the directory path is set in the environment:
section of the docker-compose.yml
file. You can look up the right pathname to use from the .env.example
file.
Volta is the Vonage design system, and is used to style the Vonage API Developer Portal. To upgrade the version of Volta used:
app/assets/volta/scss
folder in the Vonage API Developer Portalscss
folder from the Volta repo in to app/assets/volta
We :heart: contributions from everyone! It is a good idea to talk to us first if you plan to add any new functionality. Otherwise, bug reports, bug fixes and feedback on the library are always appreciated. Look at the Contributor Guidelines for more information and please follow the GitHub Flow.
Follow these instructions to make updates to any content in the Vonage API Developer Portal repository.
Checkout a new branch, naming it appropriately:
git checkout -b your-branch-name
There are three types of content you can add or update, these are seperated into different folders as well
_documentation/en
directory._blog/blogposts/en
directory. There is also _blog/authors/en
, which contains the bios of the authors of the blog._changelog/
directory. Folders in this directory act as subsections and files that represent the changelog for each tool.The names of the files you create form part of the URLs used on ADP.
Once you are done with making the necessary updates in the file you can go ahead and add your changes:
git add -p
Commit the changes in your branch. Include a commit message adequately describing the update(s):
git commit -m “Add a commit message”
Push your branch in order to raise a pull request:
git push origin your-branch-name
Create a pull request in GitHub:
nexmo-developer
repository, click the Pull requests tab.This library is released under the MIT License