From 7e2d89123b2e6c88e5f917ebc8287fbf7de6878b Mon Sep 17 00:00:00 2001 From: Megvii Engine Team Date: Fri, 5 Nov 2021 19:02:05 +0800 Subject: [PATCH] ci(docstring): add sphinx autodoc build test for docstring GitOrigin-RevId: d6a4fd469a3c5759ab196a467485f9bc916393cd --- imperative/python/scripts/sphinx.sh | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100755 imperative/python/scripts/sphinx.sh diff --git a/imperative/python/scripts/sphinx.sh b/imperative/python/scripts/sphinx.sh new file mode 100755 index 00000000..deeaa1ab --- /dev/null +++ b/imperative/python/scripts/sphinx.sh @@ -0,0 +1,33 @@ +#!/bin/bash +set -e + +# This script can be used to find WARNINGs and ERRORs hide in Python docstring. +# +# * Usually we use Sphinx (https://www.sphinx-doc.org/) and its' tools +# to build HTML documentation for Python projects, such as MegEngine. +# +# * It simulates the process of automatically extracting docstrings from source code +# and try generating HTML pages, just like what MegEngine documentation will do. +# +# Install required Python dependence with pip then you will get following tools: +# +# * sphinx-apidoc: a tool for automatic generation of Sphinx sources that, +# using the autodoc extension, document a whole package in the style of +# other automatic API documentation tools. For more details: +# https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html +# +# * sphinx-build: generates documentation frome specific files. For more details: +# https://www.sphinx-doc.org/en/master/man/sphinx-build.html +# +# [NOTE]: You need build MegEngine first (target: develop) then run this script. + +DOC_PATH=`mktemp -d` +trap 'rm -rf "$DOC_PATH"' EXIT + +cd $(dirname $0)/.. + +python3 -m pip install -r requires.txt +python3 -m pip install -r requires-sphinx.txt +sphinx-apidoc -f -F -e -o $DOC_PATH/source megengine "megengine/core/ops/builtin/*" +PYTHONPATH=. sphinx-build -j auto -c . -W --keep-going \ + $DOC_PATH/source $DOC_PATH/build