Lightning API Docs

This repo contains the source code used to generate the API docs websites for LND, Loop, Pool, Faraday, and Taproot Assets Protocol: https://lightning.engineering/api-docs/

Architecture

The websites are automatically generated from the protobuf definition files (*.proto) and Swagger/OpenAPI files (*.swagger.json) found in the Github repositories of each application. These files are sourced from the following repos:

• LND: https://github.com/lightningnetwork/lnd
• Loop: https://github.com/lightninglabs/loop
• Pool: https://github.com/lightninglabs/pool
• Faraday: https://github.com/lightninglabs/faraday
• Taproot Assets Protocol: https://github.com/lightninglabs/taproot-assets
• Lightning Terminal (LiT): https://github.com/lightninglabs/lightning-terminal

There is a multi-stage pipeline to consume the protobuf & Swagger files and convert them into an HTML static website. The process is as follows:

+ ./generate.sh
  |
  | - downloads the master branch of each repo
  | - uses protoc to convert *.proto to generated.json
  | - compiles `cmd/mdgen/main.go` into ./mdgen console app
  |
+ ./mdgen
  |
  | - outputs markdown files into site/docs/
  |
+ yarn build
  |
  | - builds the Docusaurus site
  | - converts the markdown pages into HTML
  |
+ Output Static Website

This process is run every day at midnight UTC by a cron job. After the build, the static sites are deployed.

Development

Follow these steps to run the pipeline locally. You can modify the source code for the mdgen tool and the markdown templates (in templates/), to alter the generated static pages.

System Requirements

• Go v1.18+
• protoc v3.6.0 (newer versions may not work as expected)
• NodeJS v16.x or v18.x

Initial Setup

1. Clone this repo

   $ git clone https://github.com/lightninglabs/lightning-api-ng.git
   $ cd lightning-api-ng

2. Install NodeJS dependencies

   $ cd site/
   $ yarn

Active development

1. Run the script to generate JSON files for each daemon from their proto files

   $ ./generate.sh

2. In one terminal, start the script to watch for changes of source files and automatically regenerate the markdown files

   $ ./watch.sh

3. In a second terminal, start the Docusaurus site

   $ cd site/
   $ yarn start

4. A new browser window should automatically open http://localhost:3000/api-docs/

Building the static website for deployment

1. Run the script to generate JSON files for each daemon from their proto files

   $ ./generate.sh

2. Build the static site

   $ cd site/
   $ yarn build