Commit 4c9b988f authored by Boris Glimcher's avatar Boris Glimcher Committed by Tomasz Zawadzki
Browse files

docs: generate jsonrpc.md from schema 

adding new py script to generate markdown doc for rpcs
I'm using Jinja2 here https://jinja.palletsprojects.com/


It is very flexible but also standard way to do templates

squeshed with next patch to reduce git diff

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


Tested-by: default avatarSPDK Automated Test System <spdkbot@gmail.com>
Reviewed-by: default avatarJim Harris <jim.harris@nvidia.com>
Reviewed-by: default avatarTomasz Zawadzki <tomasz@tzawadzki.com>
Reviewed-by: default avatarKonrad Sztyber <ksztyber@nvidia.com>
parent 1f56e058

.gitignore

+1 −0
Original line number Diff line number Diff line
@@ -38,6 +38,7 @@ mk/config.mk 
mk/cc.flags.mk

PYTHON_COMMAND

python/spdk/version.py

doc/jsonrpc.md

test_completions.txt

timing.txt

test/common/build_config.sh

doc/Makefile

+8 −3
Original line number Diff line number Diff line
@@ -3,10 +3,12 @@ 
#  All rights reserved.

#



SPDK_ROOT_DIR := $(abspath $(CURDIR)/..)



all: doc

	@:



.PHONY: all doc clean

.PHONY: all doc jsonrpc clean



doc: output
@@ -21,9 +23,12 @@ changelog.md: ../CHANGELOG.md 
	    -e '/# v..\...:/s/\./-/2' \

	    < $< > $@



output: Doxyfile changelog.md deprecation.md $(wildcard *.md) $(wildcard ../include/spdk/*.h)

jsonrpc:

	$(Q)$(SPDK_ROOT_DIR)/scripts/genrpc.py --schema ../schema/schema.json --doc > jsonrpc.md



output: jsonrpc Doxyfile changelog.md deprecation.md $(wildcard *.md) $(wildcard ../include/spdk/*.h)

	$(Q)rm -rf $@

	$(Q)doxygen Doxyfile



clean:

	$(Q)rm -rf output changelog.md deprecation.md
 
	$(Q)rm -rf output changelog.md deprecation.md jsonrpc.md

doc/jsonrpc.md→doc/jsonrpc.md.jinja2

+290 −1294

File changed and moved.

Preview size limit exceeded, changes collapsed.

schema/schema.json

+37 −7
Original line number Diff line number Diff line
@@ -1129,6 +1129,36 @@ 
          "type": "boolean",

          "required": false,

          "description": "Protection information is in the first 8 bytes of metadata. Default=false."

        },

        {

          "name": "preferred_write_granularity",

          "type": "number",

          "required": false,

          "description": "Preferred write granularity in blocks"

        },

        {

          "name": "preferred_write_alignment",

          "type": "number",

          "required": false,

          "description": "Preferred write alignment in blocks"

        },

        {

          "name": "optimal_write_size",

          "type": "number",

          "required": false,

          "description": "Optimal write size in blocks"

        },

        {

          "name": "preferred_unmap_granularity",

          "type": "number",

          "required": false,

          "description": "Preferred unmap granularity in blocks"

        },

        {

          "name": "preferred_unmap_alignment",

          "type": "number",

          "required": false,

          "description": "Preferred unmap alignment in blocks"

        }

      ]

    },
@@ -3634,6 +3664,12 @@ 
          "type": "boolean",

          "required": false,

          "description": "Use NVMe passthrough for I/O commands and namespace-directed admin commands. Default: `false`"

        },

        {

          "name": "enable_nssr",

          "type": "boolean",

          "required": false,

          "description": "Enable NSSR (NVMe subsystem reset). Default: `false`"

        }

      ]

    },
@@ -5600,13 +5636,7 @@ 
          "name": "zerocopy_threshold",

          "type": "number",

          "required": false,

          "description": "Set zerocopy_threshold in bytes. A consecutive sequence of requests' iovecs"

        },

        {

          "name": "--",

          "type": "--",

          "required": false,

          "description": "that fall below this threshold may be sent without zerocopy flag set"

          "description": "Set zerocopy_threshold in bytes. A consecutive sequence of requests' iovecs that fall below this threshold may be sent without zerocopy flag set"

        },

        {

          "name": "tls_version",

scripts/check_format.sh

+1 −1
Original line number Diff line number Diff line
@@ -744,7 +744,7 @@ function check_json_rpc() { 


	echo -n "Checking that all RPCs are documented..."

	while IFS='"' read -r _ rpc _; do

		if ! grep -q "^### $rpc" doc/jsonrpc.md; then

		if ! grep -q "^### $rpc" doc/jsonrpc.md.jinja2; then

			echo "Missing JSON-RPC documentation for ${rpc}"

			rc=1

		fi