[Bf-blender-cvs] [84901adec55] master: PyDoc: cleanup doc-generator
Campbell Barton
noreply at git.blender.org
Sun May 22 05:36:34 CEST 2022
Commit: 84901adec55eb1472652a315e3401a53787efcb6
Author: Campbell Barton
Date: Sat May 21 16:33:35 2022 +1000
Branches: master
https://developer.blender.org/rB84901adec55eb1472652a315e3401a53787efcb6
PyDoc: cleanup doc-generator
- Full sentences for comments.
- Use double quotes for strings (which aren't enum ID's).
- Reduce right-shift.
===================================================================
M doc/python_api/sphinx_doc_gen.py
===================================================================
diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py
index 0a20bd83c22..24b94f170c7 100644
--- a/doc/python_api/sphinx_doc_gen.py
+++ b/doc/python_api/sphinx_doc_gen.py
@@ -2,8 +2,7 @@
# <pep8 compliant>
-SCRIPT_HELP_MSG = """
-
+"""
API dump in RST files
---------------------
Run this script from Blender's root path once you have compiled Blender
@@ -36,18 +35,17 @@ Sphinx: PDF generation
sphinx-build -b latex doc/python_api/sphinx-in doc/python_api/sphinx-out
cd doc/python_api/sphinx-out
make
-
"""
try:
- import bpy # Blender module
+ import bpy # Blender module.
except ImportError:
print("\nERROR: this script must run from inside Blender")
- print(SCRIPT_HELP_MSG)
+ print(__doc__)
import sys
sys.exit()
-import rna_info # Blender module
+import rna_info # Blender module.
def rna_info_BuildRNAInfo_cache():
@@ -74,10 +72,10 @@ PLATFORM = platform().split('-')[0].lower() # 'linux', 'darwin', 'windows'
SCRIPT_DIR = os.path.abspath(os.path.dirname(__file__))
-# For now, ignore add-ons and internal subclasses of 'bpy.types.PropertyGroup'.
+# For now, ignore add-ons and internal sub-classes of `bpy.types.PropertyGroup`.
#
# Besides disabling this line, the main change will be to add a
-# 'toctree' to 'write_rst_index' which contains the generated rst files.
+# 'toctree' to 'write_rst_index' which contains the generated RST files.
# This 'toctree' can be generated automatically.
#
# See: D6261 for reference.
@@ -85,92 +83,109 @@ USE_ONLY_BUILTIN_RNA_TYPES = True
def handle_args():
- '''
+ """
Parse the args passed to Blender after "--", ignored by Blender
- '''
+ """
import argparse
# When --help is given, print the usage text
parser = argparse.ArgumentParser(
formatter_class=argparse.RawTextHelpFormatter,
- usage=SCRIPT_HELP_MSG
+ usage=__doc__
)
# optional arguments
- parser.add_argument("-p", "--partial",
- dest="partial",
- type=str,
- default="",
- help="Use a wildcard to only build specific module(s)\n"
- "Example: --partial bmesh*\n",
- required=False)
-
- parser.add_argument("-f", "--fullrebuild",
- dest="full_rebuild",
- default=False,
- action='store_true',
- help="Rewrite all rst files in sphinx-in/ "
- "(default=False)",
- required=False)
-
- parser.add_argument("-b", "--bpy",
- dest="bpy",
- default=False,
- action='store_true',
- help="Write the rst file of the bpy module "
- "(default=False)",
- required=False)
-
- parser.add_argument("-o", "--output",
- dest="output_dir",
- type=str,
- default=SCRIPT_DIR,
- help="Path of the API docs (default=<script dir>)",
- required=False)
-
- parser.add_argument("-B", "--sphinx-build",
- dest="sphinx_build",
- default=False,
- action='store_true',
- help="Build the html docs by running:\n"
- "sphinx-build SPHINX_IN SPHINX_OUT\n"
- "(default=False; does not depend on -P)",
- required=False)
-
- parser.add_argument("-P", "--sphinx-build-pdf",
- dest="sphinx_build_pdf",
- default=False,
- action='store_true',
- help="Build the pdf by running:\n"
- "sphinx-build -b latex SPHINX_IN SPHINX_OUT_PDF\n"
- "(default=False; does not depend on -B)",
- required=False)
-
- parser.add_argument("-R", "--pack-reference",
- dest="pack_reference",
- default=False,
- action='store_true',
- help="Pack all necessary files in the deployed dir.\n"
- "(default=False; use with -B and -P)",
- required=False)
-
- parser.add_argument("-l", "--log",
- dest="log",
- default=False,
- action='store_true',
- help="Log the output of the API dump and sphinx|latex "
- "warnings and errors (default=False).\n"
- "If given, save logs in:\n"
- "* OUTPUT_DIR/.bpy.log\n"
- "* OUTPUT_DIR/.sphinx-build.log\n"
- "* OUTPUT_DIR/.sphinx-build_pdf.log\n"
- "* OUTPUT_DIR/.latex_make.log",
- required=False)
-
- # parse only the args passed after '--'
+ parser.add_argument(
+ "-p", "--partial",
+ dest="partial",
+ type=str,
+ default="",
+ help="Use a wildcard to only build specific module(s)\n"
+ "Example: --partial bmesh*\n",
+ required=False,)
+
+ parser.add_argument(
+ "-f", "--fullrebuild",
+ dest="full_rebuild",
+ default=False,
+ action='store_true',
+ help="Rewrite all RST files in sphinx-in/ "
+ "(default=False)",
+ required=False,
+ )
+
+ parser.add_argument(
+ "-b", "--bpy",
+ dest="bpy",
+ default=False,
+ action='store_true',
+ help="Write the RST file of the bpy module "
+ "(default=False)",
+ required=False,
+ )
+
+ parser.add_argument(
+ "-o", "--output",
+ dest="output_dir",
+ type=str,
+ default=SCRIPT_DIR,
+ help="Path of the API docs (default=<script dir>)",
+ required=False,
+ )
+
+ parser.add_argument(
+ "-B", "--sphinx-build",
+ dest="sphinx_build",
+ default=False,
+ action='store_true',
+ help="Build the html docs by running:\n"
+ "sphinx-build SPHINX_IN SPHINX_OUT\n"
+ "(default=False; does not depend on -P)",
+ required=False,
+ )
+
+ parser.add_argument(
+ "-P", "--sphinx-build-pdf",
+ dest="sphinx_build_pdf",
+ default=False,
+ action='store_true',
+ help="Build the pdf by running:\n"
+ "sphinx-build -b latex SPHINX_IN SPHINX_OUT_PDF\n"
+ "(default=False; does not depend on -B)",
+ required=False,
+ )
+
+ parser.add_argument(
+ "-R", "--pack-reference",
+ dest="pack_reference",
+ default=False,
+ action='store_true',
+ help="Pack all necessary files in the deployed dir.\n"
+ "(default=False; use with -B and -P)",
+ required=False,
+ )
+
+ parser.add_argument(
+ "-l", "--log",
+ dest="log",
+ default=False,
+ action='store_true',
+ help=(
+ "Log the output of the API dump and sphinx|latex "
+ "warnings and errors (default=False).\n"
+ "If given, save logs in:\n"
+ "* OUTPUT_DIR/.bpy.log\n"
+ "* OUTPUT_DIR/.sphinx-build.log\n"
+ "* OUTPUT_DIR/.sphinx-build_pdf.log\n"
+ "* OUTPUT_DIR/.latex_make.log"
+ ),
+ required=False,
+ )
+
+ # Parse only the arguments passed after "--".
argv = []
if "--" in sys.argv:
- argv = sys.argv[sys.argv.index("--") + 1:] # get all args after "--"
+ argv = sys.argv[sys.argv.index("--") + 1:] # Get all arguments after "--".
return parser.parse_args(argv)
@@ -179,7 +194,7 @@ ARGS = handle_args()
# ----------------------------------BPY-----------------------------------------
-BPY_LOGGER = logging.getLogger('bpy')
+BPY_LOGGER = logging.getLogger("bpy")
BPY_LOGGER.setLevel(logging.DEBUG)
"""
@@ -193,7 +208,7 @@ or
./blender -b -noaudio --factory-startup -P doc/python_api/sphinx_doc_gen.py -- -f -B
"""
-# Switch for quick testing so doc-builds don't take so long
+# Switch for quick testing so doc-builds don't take so long.
if not ARGS.partial:
# full build
FILTER_BPY_OPS = None
@@ -261,7 +276,7 @@ else:
# ------
# Filter
#
- # TODO, support bpy.ops and bpy.types filtering
+ # TODO: support `bpy.ops` and `bpy.types` filtering.
import fnmatch
m = None
EXCLUDE_MODULES = [m for m in EXCLUDE_MODULES if not fnmatch.fnmatchcase(m, ARGS.partial)]
@@ -293,13 +308,13 @@ else:
try:
__import__("aud")
except ImportError:
- BPY_LOGGER.debug("Warning: Built without 'aud' module, docs incomplete...")
+ BPY_LOGGER.debug("Warning: Built without \"aud\" module, docs incomplete...")
EXCLUDE_MODULES.append("aud")
try:
__import__("freestyle")
except ImportError:
- BPY_LOGGER.debug("Warning: Built without 'freestyle' module, docs incomplete...")
+ BPY_LOGGER.debug("Warning: Built without \"freestyle\" module, docs incomplete...")
EXCLUDE_MODULES.extend([
"freestyle",
"freestyle.chainingiterators",
@@ -335,7 +350,7 @@ for f in os.listdir(EXAMPLES_DIR):
EXAMPLE_SET.add(os.path.splitext(f)[0])
EXAMPLE_SET_USED = set()
-# rst files dir
+# RST files directory.
RST_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "rst"))
# extra info, not api reference docs
@@ -364,33 +379,33 @@ RNA_BLACKLIST = {
MODULE_GROUPING = {
"bmesh.types": (
- ("Base Mesh Type", '-'),
+ ("Base Mesh Type", "-"),
"BMesh",
- ("Mesh Elements", '-'),
+ ("Mesh Elements", "-"),
"BMVert",
"BMEdge",
"BMFace",
"BMLoop",
- ("Sequence Accessors", '-'),
+ ("Sequence Accessors", "-"),
"BMElemSeq",
"BMVertSeq",
"BMEdgeSeq",
"BMFaceSeq",
"BMLoopSeq",
"BMIter
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list