Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add http/openapi documentation & ci workflow #2678

Merged
merged 4 commits into from
Jun 4, 2024
Merged

docs: Add http/openapi documentation & ci workflow #2678

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a3e29d9
PR: Remove extra step from cli docs action
shahzadlone Jun 3, 2024
acc71a8
PR: Add the http openapi document gen make rule
shahzadlone Jun 3, 2024
67f8339
PR: Run the open-api generation `make` command
shahzadlone Jun 3, 2024
2cc8e99
PR: Add workflow to check http documentation
shahzadlone Jun 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 0 additions & 9 deletions .github/workflows/check-cli-documentation.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,15 +35,6 @@ jobs:
- name: Checkout code into the directory
uses: actions/checkout@v3

# This check is there as a safety to ensure we start clean (without any changes).
fredcarle marked this conversation as resolved.
Show resolved Hide resolved
# If there are ever changes here, the rest of the job will output false result.
- name: Check no changes exist initially
uses: tj-actions/verify-changed-files@v20
with:
fail-if-changed: true
files: |
docs/website/references/cli
- name: Setup Go environment explicitly
uses: actions/setup-go@v3
with:
Expand Down
52 changes: 52 additions & 0 deletions .github/workflows/check-http-documentation.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Copyright 2024 Democratized Data Foundation
#
# Use of this software is governed by the Business Source License
# included in the file licenses/BSL.txt.
#
# As of the Change Date specified in that file, in accordance with
# the Business Source License, use of this software will be governed
# by the Apache License, Version 2.0, included in the file
# licenses/APL.txt.

# This workflow checks that all HTTP documentation is up to date.
# If the documentation is not up to date then this action will fail.
name: Check HTTP Documentation Workflow

on:
pull_request:
branches:
- master
- develop

push:
tags:
- 'v[0-9]+.[0-9]+.[0-9]+'
branches:
- master
- develop

jobs:
check-http-documentation:
name: Check http documentation job

runs-on: ubuntu-latest

steps:
- name: Checkout code into the directory
uses: actions/checkout@v3

- name: Setup Go environment explicitly
uses: actions/setup-go@v3
with:
go-version: "1.21"
check-latest: true

- name: Try generating http documentation
run: make docs:http

- name: Check no new changes exist
uses: tj-actions/verify-changed-files@v20
with:
fail-if-changed: true
files: |
docs/website/references/http
5 changes: 5 additions & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -356,12 +356,17 @@ chglog:
docs:
@$(MAKE) docs\:cli
@$(MAKE) docs\:manpages
@$(MAKE) docs\:http

.PHONY: docs\:cli
docs\:cli:
rm -f docs/website/references/cli/*.md
go run cmd/genclidocs/main.go -o docs/website/references/cli

.PHONY: docs\:http
docs\:http:
go run cmd/genopenapi/main.go | python -m json.tool > docs/website/references/http/openapi.json
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question: Why do we want to have the openAPI json output published in our docs? I'm asking because it's not really something to be read by humans.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we can have it render a UI like this with some config options https://docs.source.network/sourcehub/api

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. Hopefully we can make the table easier to read because the one at the link is pretty terrible 😅

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is one of my favourite API docs: https://docs.stripe.com/api
If we can eventually make it look like this but on top of it be able to execute the request to a configurable endpoint, that would be amazing.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is one of my favourite API docs: docs.stripe.com/api If we can eventually make it look like this but on top of it be able to execute the request to a configurable endpoint, that would be amazing.

Nice the stripe docs look really nice. Whoever is responsible for website doc stuff can easily plug it in using the json file this PR introduces


.PHONY: docs\:manpages
docs\:manpages:
go run cmd/genmanpages/main.go -o build/man/
Expand Down
Loading
Loading