Commit 1acd8052 authored by Boris Glimcher's avatar Boris Glimcher Committed by Tomasz Zawadzki
Browse files

doc: fix json examples and lint them 



RPC examples are in json format but written by a human
so a lot of mistakes are being made

Previous patches fixed most of the errors, so
this patch finally enables the linting of the json here.

Change-Id: I41f9a0ef24aa53a7c44bcccd54d588313103eecc
Signed-off-by: default avatarBoris Glimcher <Boris.Glimcher@emc.com>
Reviewed-on: https://review.spdk.io/c/spdk/spdk/+/26762


Reviewed-by: default avatarKonrad Sztyber <ksztyber@nvidia.com>
Tested-by: default avatarSPDK Automated Test System <spdkbot@gmail.com>
Reviewed-by: default avatarTomasz Zawadzki <tomasz@tzawadzki.com>
parent 69608bfc

doc/jsonrpc.md.jinja2

+2 −2
Original line number Diff line number Diff line
@@ -3599,7 +3599,7 @@ Example request: 
    "preferred_write_alignment": 64,

    "optimal_write_size": 4,

    "preferred_unmap_granularity": 16,

    "preferred_unmap_alignment": 16,

    "preferred_unmap_alignment": 16

  },

  "jsonrpc": "2.0",

  "method": "bdev_null_create",
@@ -8244,7 +8244,7 @@ Example response: 
  "result": [

    {

      "cntlid": 1,

      "cntrltype: "io",

      "cntrltype": "io",

      "hostnqn": "nqn.2016-06.io.spdk:host1",

      "hostid": "27dad528-6368-41c3-82d3-0b956b49025d",

      "num_io_qpairs": 5

scripts/check_format.sh

+16 −0
Original line number Diff line number Diff line
@@ -802,6 +802,21 @@ function check_rpc_args() { 
	return $rc

}



function check_rpc_schema() {

	local rc=0



	echo -n "Linting Schema RPCs and documentation..."

	if ! python "$rootdir"/scripts/genrpc.py --schema "$rootdir"/schema/schema.json > badargs.log 2>&1; then

		echo "Found bogus JSON in doc/jsonrpc.md.jinja2"

		cat badargs.log

		rc=1

	else

		echo " OK"

	fi

	rm -f badargs.log

	return $rc

}



function get_files_for_lic() {

	local f_shebang="" f_suffix=() f_type=() f_all=() exceptions=""
@@ -947,6 +962,7 @@ check_bash_static_analysis || rc=1 
check_changelog || rc=1

check_json_rpc || rc=1

check_rpc_args || rc=1

check_rpc_schema || rc=1

check_spdx_lic || rc=1

check_golang_style || rc=1

check_extern_c || rc=1

scripts/genrpc.py

+21 −3
Original line number Diff line number Diff line
@@ -5,6 +5,8 @@ 
#



import os

import re

import sys

import json

import argparse

from pathlib import Path
@@ -15,6 +17,19 @@ from jinja2 import Environment, FileSystemLoader 
base_dir = Path(__file__).resolve().parent.parent





def lint_json_examples():

    with open(base_dir / "doc" / "jsonrpc.md.jinja2", "r") as file:

        data = file.read()

        examples = re.findall("~~~json(.+?)~~~", data, re.MULTILINE | re.DOTALL)

        for example in examples:

            try:

                json.loads(example)

            except json.decoder.JSONDecodeError:

                for i, x in enumerate(example.splitlines()):

                    print(i+1, x, file=sys.stderr)

                raise





def generate_docs(schema):

    env = Environment(loader=FileSystemLoader(base_dir / "doc"),

                      keep_trailing_newline=True,
@@ -76,15 +91,18 @@ if __name__ == "__main__": 


    args = parser.parse_args()



    try:

        lint_json_examples()

    except ValueError as e:

        print(f"Error: {e}", file=sys.stderr)

        sys.exit(1)



    if not os.path.exists(args.schema):

        raise FileNotFoundError(f'Cannot access {args.schema}: No such file or directory')



    with open(args.schema, "r") as file:

        schema = json.load(file)



    if not (args.doc or args.rpc):

        parser.error("No action requested, add -d for doc or -r for rpcs generation")



    if args.doc:

        generate_docs(schema)

    if args.rpc: