Fidldoc is a command-line tool that generates reference pages based on FIDL JSON IR.
fx set
(e.g. fx set core.x64 --with //tools/fidl/fidldoc
)fx build tools/fidl/fidldoc:fidldoc
fx fidldoc fuchsia-device.fidl.json
fx fidldoc json/*
By default, docs will be generated in ./docs/
. You can change that by specifying the --output
(or -o
) command-line flag. Use the --template
(or -t
) flag to select the output format. Currently, the two supported values are markdown
and html
.
Additional configurations can be provided in a fidldoc.config.json
file and passed as part of the command line interface.
Example:
fx fidldoc -v \ ./out/x64/fidling/gen/zircon/system/fidl/fuchsia-mem/fuchsia-mem.fidl.json \ -c ./out/default/host_x64/fidldoc.config.json
The all_fidl_json.txt
file provides a list of file locations to all of the FIDL JSON IR files that are part of the Fuchsia build. You can use this file to generate all of the reference docs. The snippet below shows an example of how to do it:
FIDL_PATHS=$(cat ./out/default/all_fidl_json.txt | sed -e 's/^/.\/out\/default\//') fx fidldoc -v $(echo $FIDL_PATHS)
You can optionally pass a --tag
flag to specify a source definition.
Example - How to use the --tag
flag to point to the current git commit or branch:
fx fidldoc -v \ ./out/x64/fidling/gen/zircon/system/fidl/fuchsia-mem/fuchsia-mem.fidl.json \ -c ./out/default/host_x64/fidldoc.config.json \ --tag $(git rev-parse HEAD)
The tests
target will generate a unit test binary in the build output directory.
fx set core.x64 --with //tools/fidl/fidldoc:tests
fx test host_x64/fidldoc_bin_test
The test golden_test
uses .json.golden
files from //zircon/tools/fidl/goldens
as input, and compares the generated output with the goldens from src/templates/markdown/testdata
.
To regenerate the goldens run:
REGENERATE_GOLDENS_FOLDER=$FUCHSIA_DIR/tools/fidl/fidldoc/src/templates/markdown/testdata \ fx test host_x64/fidldoc_bin_test -- golden_test