Lightning Network Daemon API Documentation Site
API Documentation for the Lightning Network Daemon, powered by Slate
This repository contains functionality for programmatically pulling API
lncli -h and
rpc.proto on the lnd Github, using a Python
script and Jinja2 template to output Slate markdown, which itself generates the
fully rendered static site.
Pay special attention to these files:
templates/index_templates.md: The Jinja2 template fed into the Python script, holding the basic format and introductory information for the site
update_and_render.sh: Update local docs to the latest version available
render.py: The Python script that uses local docs and Jinja template to output Slate markdown
deploy.sh: Build static site from Slate markdown and deploy to Google Cloud Platform
Running the site locally
You're going to need:
- Linux or OS X — Windows may work, but is unsupported.
- Ruby, version 2.2.5 or newer
- Python, version 3 or newer
- Bundler — If Ruby is already installed, but the
bundlecommand doesn't work, just run
gem install bundlerin a terminal.
git clone https://github.com/lightninglabs/lightning-api # Start a local server for testing purposes bundle install --path vendor/bundle bundle exec middleman server
You can now see the docs at
# Install Jinja for python templating. pip3 install Jinja2 # Set your $GOPATH to a directory that has access to lncli. export GOPATH="/path/to/lnd" export PATH=$PATH:$GOPATH/bin # Install annotations and protoc-gen-doc. go get -u github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc # Get the latest rpc.proto. curl -o rpc.proto -s https://raw.githubusercontent.com/lightningnetwork/lnd/master/lnrpc/rpc.proto curl -o rpc.swagger.json -s https://raw.githubusercontent.com/lightningnetwork/lnd/master/lnrpc/rpc.swagger.json # Generate the rpc.json file from rpc.proto, so that render.py can parse it. protoc -I. -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis --doc_out=json,rpc.json:. rpc.proto
Now, ensure that you have
$GOPATH set, so that
lncli is available from the command line.
Let's run the script to render our local Slate docs:
Now that you're all set up, you can just run
automatically pull the latest rpc.proto and render the local Slate docs.
The Lightning API is deployed with Google Cloud Platform. Visit this blog post for more information.
- Install Google Cloud SDK and authenticate into it:
brew cask install google-cloud-sdk gcloud auth login
bundle exec middleman build --clean
- Push to Google Cloud Bucket
# -m use faster multithreaded uploads # -d delete remote files that aren't in the source # -r recurse into source subdirectories gsutil -m rsync -d -r ./_site gs://api.lightning.community
In the future, you can just run
./deploy.sh to deploy automatically.
Automatic Updates and Deployment
Updates to the protobuf definitions can be detected by running the Flask server
Running the server locally
The server uses Flask in order to receive POST requests from GitHub whenever a new commit has been pushed to the respository. These POST requests will include the HMAC of a secret token set up within the Webhook settings of a repository. This token will need to be exported so that the server can verify the request from GitHub has been authenticated.
First, ensure that
Flask is installed with:
$ pip3 install flask
Then, the server can be run with:
$ export WEBHOOK_SECRET_TOKEN=YOUR_TOKEN_HERE $ FLASK_APP=app.py $ flask run
Once a POST request from GitHub has been received, the server will check if there were any commits which included a change to the protobuf definitions. If there was, then the documentation will be automatically regenerated and deployed.