#!/usr/bin/env python3 """ build.py -- Generate LVGL documentation using Doxygen and Sphinx + Breathe. Synopsis -------- - $ python build.py html [ skip_api ] [ fresh_env ] - $ python build.py latex [ skip_api ] [ fresh_env ] - $ python build.py intermediate [ skip_api ] - $ python build.py clean - $ python build.py clean_intermediate - $ python build.py clean_html - $ python build.py clean_latex Build Arguments and Clean Arguments can be used one at a time or be freely mixed and combined. Description ----------- Copy source files to an intermediate directory and modify them there before doc generation occurs. If a full rebuild is being done (e.g. after a `clean`) run Doxygen LVGL's source files to generate intermediate API information in XML format. Generate API documents for Breathe's consumption. Add API links to end of some documents. Generate example documents. From there, Sphinx with Breathe extension uses the resulting set of intermediate files to generate the desired output. It is only during this first build that the `skip_api` option has meaning. After the first build, no further actions is taken regarding API pages since they are not regenerated after the first build. The intermediate directory has a fixed location (overridable by `LVGL_DOC_BUILD_INTERMEDIATE_DIR` environment variable) and by default this script attempts to rebuild only those documents whose path, name or modification date has changed since the last build. The output directory also has a fixed location (overridable by `LVGL_DOC_BUILD_OUTPUT_DIR` environment variable). Caution: The document build meant for end-user consumption should ONLY be done after a `clean` unless you know that no API documentation and no code examples have changed. A `sphinx-build` will do a full doc rebuild any time: - the intermediate directory doesn't exist or is empty (since the new files in the intermediate directory will have modification times after the generated HTML or Latex files, even if nothing changed), - the targeted output directory doesn't exist or is empty, or - Sphinx determines that a full rebuild is necessary. This happens when: - intermediate directory (Sphinx's source-file path) has changed, - any options on the `sphinx-build` command line have changed, - `conf.py` modification date has changed, or - `fresh_env` argument is included (runs `sphinx-build` with -E option). Typical run time: Full build: 22.5 min skip_api : 1.9 min (applies to first build only) Options ------- help Print usage note and exit with status 0. html [ skip_api ] [ fresh_env ] Build HTML output. `skip_api` only has effect on first build after a `clean` or `clean_intermediate`. latex [ skip_api ] [ fresh_env ] Build Latex/PDF output (on hold pending removal of non-ASCII characters from input files). `skip_api` only has effect on first build after a `clean` or `clean_intermediate`. intermediate [ skip_api ] Generate intermediate directory contents (ready to build output formats). If they already exist, they are removed and re-generated. Note: "intermediate" can be abbreviated down to "int". skip_api (with `html` and/or `latex` and/or `intermediate` options) Skip API pages and links when intermediate directory contents are being generated (saving about 91% of build time). Note: they are not thereafter regenerated unless requested by `intermediate` argument or the intermediate directory does not exist. This is intended to be used only during doc development to speed up turn-around time between doc modifications and seeing final results. fresh_env (with `html` and/or `latex` options) Run `sphinx-build` with -E command-line argument, which makes it regenerate its "environment" (memory of what was built previously, forcing a full rebuild). clean Remove all generated files. clean_intermediate Remove intermediate directory. Note: "clean_intermediate" can be abbreviated down to "clean_int". clean_html Remove HTML output directory. clean_latex Remove Latex output directory. Unrecognized arguments print error message, usage note, and exit with status 1. Python Package Requirements --------------------------- The list of Python package requirements are in `requirements.txt`. Install them by: $ pip install -r requirements.txt History ------- The first version of this file (Apr 2021) discovered the name of the current branch (e.g. 'master', 'release/v8.4', etc.) to support different versions of the documentation by establishing the base URL (used in `conf.py` and in [Edit on GitHub] links), and then ran: - Doxygen (to generate LVGL API XML), then - Sphinx to generate the LVGL document tree. Internally, Sphinx uses `breathe` (a Sphinx extension) to provide a bridge between Doxygen XML output and Sphinx documentation. It also supported a command-line option `clean` to remove generated files before starting (eliminates orphan files, for docs that have moved or changed). Since then its duties have grown to include: - Using environment variables to convey branch names to several more places where they are used in the docs-generating process (instead of re-writing writing `conf.py` and a `header.rst` each time docs were generated). These are documented where they generated below. - Supporting additional command-line options. - Generating a `./docs/lv_conf.h` for Doxygen to use (config_builder.py). - Supporting multiple execution platforms (which then required tokenizing Doxygen's INPUT path in `Doxyfile` and re-writing portions that used `sed` to generate input or modify files). - Adding translation and API links (requiring generating docs in an intermediate directory so that the links could be programmatically added to each document before Sphinx was run). Note: translation link are now done manually since they are only on the main landing page. - Generating EXAMPLES page + sub-examples where applicable to individual documents, e.g. to widget-, style-, layout-pages, etc. - Building PDF via latex (when working). - Shifting doc-generation paradigm to behave more like `make`. """ # **************************************************************************** # IMPORTANT: If you are getting a PDF-lexer error for an example, check # for extra lines at the end of the file. Only a single empty line # is allowed!!! Ask me how long it took me to figure this out. # -- @kdschlosser # **************************************************************************** # Python Library import sys import os import subprocess import shutil import dirsync from datetime import datetime # LVGL Custom import example_list import doc_builder import config_builder _ = os.path.abspath(os.path.dirname(__file__)) docs_src_dir = os.path.join(_, 'src') sys.path.insert(0, docs_src_dir) from lvgl_version import lvgl_version # NoQA # Not Currently Used # (Code is kept in case we want to re-implement it later.) # import add_translation # ------------------------------------------------------------------------- # Configuration # ------------------------------------------------------------------------- # These are relative paths from the ./docs/ directory. cfg_project_dir = '..' cfg_src_dir = 'src' cfg_examples_dir = 'examples' cfg_default_intermediate_dir = 'intermediate' cfg_default_output_dir = 'build' cfg_static_dir = '_static' cfg_downloads_dir = 'downloads' cfg_lv_conf_filename = 'lv_conf.h' cfg_lv_version_filename = 'lv_version.h' cfg_doxyfile_filename = 'Doxyfile' cfg_top_index_filename = 'index.rst' # Filename generated in `latex_output_dir` and copied to `pdf_output_dir`. cfg_pdf_filename = 'LVGL.pdf' # ------------------------------------------------------------------------- # Print usage note. # ------------------------------------------------------------------------- def print_usage_note(): print('Usage:') print(' $ python build.py [optional_arg ...]') print() print(' where `optional_arg` can be any of these:') print(' html [ skip_api ] [ fresh_env ]') print(' latex [ skip_api ] [ fresh_env ]') print(' intermediate [ skip_api ]') print(' clean') print(' clean_intermediate') print(' clean_html') print(' clean_latex') print(' help') def remove_dir(tgt_dir): """Remove directory `tgt_dir`.""" if os.path.isdir(tgt_dir): print(f'Removing {tgt_dir}...') shutil.rmtree(tgt_dir) else: print(f'{tgt_dir} already removed...') def cmd(s, start_dir=None, exit_on_error=True): """Run external command and abort build on error.""" if start_dir is None: start_dir = os.getcwd() saved_dir = os.getcwd() os.chdir(start_dir) print("") print(s) print("-------------------------------------") result = os.system(s) os.chdir(saved_dir) if result != 0 and exit_on_error: print("Exiting build due to previous error.") sys.exit(result) def intermediate_dir_contents_exists(dir): """Provide answer to question: Can we have reasonable confidence that the contents of `intermediate_directory` already exists? """ result = False c1 = os.path.isdir(dir) if c1: temp_path = os.path.join(dir, 'CHANGELOG.rst') c2 = os.path.exists(temp_path) temp_path = os.path.join(dir, '_ext') c3 = os.path.isdir(temp_path) temp_path = os.path.join(dir, '_static') c4 = os.path.isdir(temp_path) temp_path = os.path.join(dir, 'details') c5 = os.path.isdir(temp_path) temp_path = os.path.join(dir, 'intro') c6 = os.path.isdir(temp_path) temp_path = os.path.join(dir, 'contributing') c7 = os.path.isdir(temp_path) temp_path = os.path.join(dir, cfg_examples_dir) c8 = os.path.isdir(temp_path) result = c2 and c3 and c4 and c5 and c6 and c7 and c8 return result def run(args): """Perform doc-build function(s) requested.""" # --------------------------------------------------------------------- # Set default settings. # --------------------------------------------------------------------- build_html = False build_latex = False build_intermediate = False skip_api = False fresh_sphinx_env = False clean_all = False clean_intermediate = False clean_html = False clean_latex = False def print_setting(setting_name, val): """Print one setting; used for debugging.""" print(f'{setting_name:18} = [{val}]') def print_settings(and_exit): """Print all settings and optionally exit; used for debugging.""" print_setting("build_html", build_html) print_setting("build_latex", build_latex) print_setting("build_intermediate", build_intermediate) print_setting("skip_api", skip_api) print_setting("fresh_sphinx_env", fresh_sphinx_env) print_setting("clean_all", clean_all) print_setting("clean_intermediate", clean_intermediate) print_setting("clean_html", clean_html) print_setting("clean_latex", clean_latex) if and_exit: exit(0) # --------------------------------------------------------------------- # Process args. # --------------------------------------------------------------------- # No args means print usage note and exit with status 0. if len(args) == 0: print_usage_note() exit(0) # Some args are present. Interpret them in loop here. # Unrecognized arg means print error, print usage note, exit with status 1. for arg in args: # We use chained `if-elif-else` instead of `match` for those on Linux # systems that will not have the required version 3.10 of Python yet. if arg == 'help': print_usage_note() exit(0) elif arg == "html": build_html = True elif arg == "latex": build_latex = True elif "intermediate".startswith(arg) and len(arg) >= 3: # Accept abbreviations. build_intermediate = True elif arg == 'skip_api': skip_api = True elif arg == 'fresh_env': fresh_sphinx_env = True elif arg == "clean": clean_all = True clean_intermediate = True clean_html = True clean_latex = True elif arg == "clean_html": clean_html = True elif arg == "clean_latex": clean_latex = True elif "clean_intermediate".startswith(arg) and len(arg) >= 9: # Accept abbreviations. # Needs to be after others so "cl" will not clean_intermediate = True else: print(f'Argument [{arg}] not recognized.') print() print_usage_note() exit(1) # '-E' option forces Sphinx to rebuild its environment so all docs are # fully regenerated, even if not changed. # Note: Sphinx runs in ./docs/, but uses `intermediate_dir` for input. if fresh_sphinx_env: print("Force-regenerating all files...") env_opt = '-E' else: env_opt = '' # --------------------------------------------------------------------- # Start. # --------------------------------------------------------------------- t0 = datetime.now() # --------------------------------------------------------------------- # Set up paths. # # Variable Suffixes: # _filename = filename without path # _path = path leading to a file or directory (absolute or relative) # _file = path leading to a file (absolute or relative) # _dir = path leading to a directory (absolute or relative) # --------------------------------------------------------------------- base_dir = os.path.abspath(os.path.dirname(__file__)) project_dir = os.path.abspath(os.path.join(base_dir, cfg_project_dir)) examples_dir = os.path.join(project_dir, cfg_examples_dir) lvgl_src_dir = os.path.join(project_dir, 'src') # Establish intermediate directory. The presence of environment variable # `LVGL_DOC_BUILD_INTERMEDIATE_DIR` overrides default in `cfg_default_intermediate_dir`. if 'LVGL_DOC_BUILD_INTERMEDIATE_DIR' in os.environ: intermediate_dir = os.environ['LVGL_DOC_BUILD_INTERMEDIATE_DIR'] else: intermediate_dir = os.path.join(base_dir, cfg_default_intermediate_dir) lv_conf_file = os.path.join(intermediate_dir, cfg_lv_conf_filename) version_dst_file = os.path.join(intermediate_dir, cfg_lv_version_filename) top_index_file = os.path.join(intermediate_dir, cfg_top_index_filename) doxyfile_src_file = os.path.join(base_dir, cfg_doxyfile_filename) doxyfile_dst_file = os.path.join(intermediate_dir, cfg_doxyfile_filename) pdf_intermediate_dst_dir = os.path.join(intermediate_dir, cfg_static_dir, cfg_downloads_dir) pdf_intermediate_dst_file = os.path.join(pdf_intermediate_dst_dir, cfg_pdf_filename) sphinx_path_sep = '/' pdf_relative_file = cfg_static_dir + sphinx_path_sep + cfg_downloads_dir + sphinx_path_sep + cfg_pdf_filename pdf_link_ref_str = f'PDF Version: :download:`{cfg_pdf_filename} <{pdf_relative_file}>`' # Establish build directory. The presence of environment variable # `LVGL_DOC_BUILD_OUTPUT_DIR` overrides default in `cfg_default_output_dir`. if 'LVGL_DOC_BUILD_OUTPUT_DIR' in os.environ: output_dir = os.environ['LVGL_DOC_BUILD_OUTPUT_DIR'] else: output_dir = os.path.join(base_dir, cfg_default_output_dir) html_output_dir = os.path.join(output_dir, 'html') latex_output_dir = os.path.join(output_dir, 'latex') pdf_output_dir = os.path.join(output_dir, 'pdf') pdf_src_file = os.path.join(latex_output_dir, cfg_pdf_filename) pdf_dst_file = os.path.join(pdf_output_dir, cfg_pdf_filename) version_src_file = os.path.join(project_dir, cfg_lv_version_filename) # Special stuff for right-aligning PDF download link. # Note: this needs to be embedded in a
tag because the # Sphinx `:download:` role causes the link to appear in a

tag # and in HTML5,

tags cannot be nested! cfg_right_just_para_text = """.. raw:: html

""" cfg_end_right_just_para_text = """.. raw:: html
""" # Blank lines are required due to the directives. cfg_pdf_link_ref_block_str = \ cfg_right_just_para_text + os.linesep \ + os.linesep \ + pdf_link_ref_str + os.linesep + \ os.linesep \ + cfg_end_right_just_para_text + os.linesep \ + os.linesep # --------------------------------------------------------------------- # Change to script directory for consistent run-time environment. # --------------------------------------------------------------------- os.chdir(base_dir) print(f'Intermediate dir: [{intermediate_dir}]') print(f'Output dir : [{output_dir}]') print(f'Running from : [{base_dir}]') # --------------------------------------------------------------------- # Clean? If so, clean (like `make clean`), but do not exit. # --------------------------------------------------------------------- some_cleaning_to_be_done = clean_intermediate or clean_html or clean_latex \ or clean_all or (os.path.isdir(intermediate_dir) and build_intermediate) if some_cleaning_to_be_done: print("****************") print("Cleaning...") print("****************") if clean_intermediate: remove_dir(intermediate_dir) if clean_html: remove_dir(html_output_dir) if clean_latex: remove_dir(latex_output_dir) if clean_all: remove_dir(output_dir) if os.path.isdir(intermediate_dir) and build_intermediate: remove_dir(intermediate_dir) # --------------------------------------------------------------------- # Populate LVGL_URLPATH and LVGL_GITCOMMIT environment variables: # - LVGL_URLPATH <= 'master' or '8.4' '9.2' etc. # - LVGL_GITCOMMIT <= same (see 03-Oct-2024 note below). # # These supply input later in the doc-generation process as follows: # # LVGL_URLPATH is used by: # - `conf.py` to build `html_baseurl` for Sphinx for # - generated index # - generated search window # - establishing canonical page for search engines # - `link_roles.py` to generate translation links # - `doc_builder.py` to generate links to API pages # # LVGL_GITCOMMIT is used by: # - `conf.py` => html_context['github_version'] for # Sphinx Read-the-Docs theme to add to [Edit on GitHub] links # - `conf.py` => repo_commit_hash for generated EXAMPLES pages for: # - [View on GitHub] buttons (view C code examples) # - [View on GitHub] buttons (view Python code examples) # --------------------------------------------------------------------- # 03-Oct-2024: Gabor requested LVGL_GITCOMMIT be changed to a branch # name since that will always be current, and it will fix a large # number of broken links on the docs website, since commits that # generated docs can sometimes go away. This gets used in: # - [Edit on GitHub] links in doc pages (via Sphinx theme), and # - [View on GitHub] links in example pages (via `example_list.py` # and `lv_example.py`). # Original code: # status, br = subprocess.getstatusoutput("git branch --show-current") # _, gitcommit = subprocess.getstatusoutput("git rev-parse HEAD") # br = re.sub(r'\* ', '', br) # 're' was previously used to remove leading '* ' from current branch # string when we were parsing output from bare `git branch` output. # This is no longer needed with `--show-current` option now used. # --------------------------------------------------------------------- status, branch = subprocess.getstatusoutput("git branch --show-current") # If above failed (i.e. `branch` not valid), default to 'master'. if status != 0: branch = 'master' elif branch == 'master': # Expected in most cases. Nothing to change. pass else: # `branch` is valid. Capture release version if in a 'release/' branch. if branch.startswith('release/'): branch = branch[8:] else: # Default to 'master'. branch = 'master' os.environ['LVGL_URLPATH'] = branch os.environ['LVGL_GITCOMMIT'] = branch # --------------------------------------------------------------------- # Copy files to 'intermediate_dir' where they will be edited (translation # link(s) and API links) before being used to generate new docs. # --------------------------------------------------------------------- # dirsync `exclude_list` = list of regex patterns to exclude. intermediate_re = r'^' + cfg_default_intermediate_dir + r'.*' output_re = r'^' + cfg_default_output_dir + r'.*' exclude_list = [r'lv_conf\.h', r'^__pycache__.*', intermediate_re, output_re] if intermediate_dir_contents_exists(intermediate_dir): # We are just doing an update of the intermediate_dir contents. print("****************") print("Updating intermediate directory...") print("****************") exclude_list.append(r'examples.*') options = { 'verbose': True, # Report files copied. 'create': True, # Create directories if they don't exist. 'twoway': False, # False means data flow only src => tgt. 'purge': False, # False means DO NOT remove orphan files/dirs in tgt dir (preserving examples/ dir). 'exclude': exclude_list } # action == 'sync' means copy files even when they do not already exist in tgt dir. # action == 'update' means DO NOT copy files when they do not already exist in tgt dir. dirsync.sync(cfg_src_dir, intermediate_dir, 'sync', **options) dirsync.sync(examples_dir, os.path.join(intermediate_dir, cfg_examples_dir), 'sync', **options) elif build_intermediate or build_html or build_latex: # We are having to create the intermediate_dir contents by copying. print("****************") print("Building intermediate directory...") print("****************") copy_method = 1 # Both of these methods work. if copy_method == 0: # --------- Method 0: ignore_func = shutil.ignore_patterns('tmp*', 'output*') print('Copying docs...') shutil.copytree(cfg_src_dir, intermediate_dir, ignore=ignore_func, dirs_exist_ok=True) print('Copying examples...') shutil.copytree(examples_dir, os.path.join(intermediate_dir, cfg_examples_dir), dirs_exist_ok=True) else: # --------- Method 1: options = { 'create': True, # Create directories if they don't exist. 'exclude': exclude_list } # action == 'sync' means copy files even when they do not already exist in tgt dir. # action == 'update' means DO NOT copy files when they do not already exist in tgt dir. print('Copying docs...') dirsync.sync(cfg_src_dir, intermediate_dir, 'sync', **options) print('Copying examples...') dirsync.sync(examples_dir, os.path.join(intermediate_dir, cfg_examples_dir), 'sync', **options) # ----------------------------------------------------------------- # Build Example docs, Doxygen output, API docs, and API links. # ----------------------------------------------------------------- t1 = datetime.now() # Build /lv_conf.h from lv_conf_template.h for this build only. config_builder.run(lv_conf_file) # Copy `lv_version.h` into intermediate directory. shutil.copyfile(version_src_file, version_dst_file) # Replace tokens in Doxyfile in 'intermediate_dir' with data from this run. with open(doxyfile_src_file, 'rb') as f: data = f.read().decode('utf-8') data = data.replace('<>', lv_conf_file) data = data.replace('<>', f'"{lvgl_src_dir}"') with open(doxyfile_dst_file, 'wb') as f: f.write(data.encode('utf-8')) # ----------------------------------------------------------------- # Generate examples pages. Include sub-pages pages that get included # in individual documents where applicable. # ----------------------------------------------------------------- print("Generating examples...") example_list.exec(intermediate_dir) # ----------------------------------------------------------------- # Add translation links. # This is being skipped in favor of a manually-placed # translation link at the top of `./docs/index.rst`. # ----------------------------------------------------------------- # Original code: # if True: # print("Skipping adding translation links.") # else: # print("Adding translation links...") # add_translation.exec(intermediate_dir) # --------------------------------------------------------------------- # Generate API pages and links thereto. # --------------------------------------------------------------------- if skip_api: print("Skipping API generation as requested.") else: print("Running Doxygen...") cmd('doxygen Doxyfile', intermediate_dir) print("API page and link processing...") doc_builder.EMIT_WARNINGS = False # Create .RST files for API pages, plus # add API hyperlinks to .RST files in the directories in passed array. doc_builder.run( project_dir, intermediate_dir, os.path.join(intermediate_dir, 'intro'), os.path.join(intermediate_dir, 'details'), os.path.join(intermediate_dir, 'details', 'common-widget-features'), os.path.join(intermediate_dir, 'details', 'common-widget-features', 'layouts'), os.path.join(intermediate_dir, 'details', 'common-widget-features', 'styles'), os.path.join(intermediate_dir, 'details', 'debugging'), os.path.join(intermediate_dir, 'details', 'integration'), os.path.join(intermediate_dir, 'details', 'integration', 'adding-lvgl-to-your-project'), os.path.join(intermediate_dir, 'details', 'integration', 'bindings'), os.path.join(intermediate_dir, 'details', 'integration', 'building'), os.path.join(intermediate_dir, 'details', 'integration', 'chip'), os.path.join(intermediate_dir, 'details', 'integration', 'driver'), os.path.join(intermediate_dir, 'details', 'integration', 'driver', 'display'), os.path.join(intermediate_dir, 'details', 'integration', 'driver', 'touchpad'), os.path.join(intermediate_dir, 'details', 'integration', 'framework'), os.path.join(intermediate_dir, 'details', 'integration', 'ide'), os.path.join(intermediate_dir, 'details', 'integration', 'os'), os.path.join(intermediate_dir, 'details', 'integration', 'os', 'yocto'), os.path.join(intermediate_dir, 'details', 'integration', 'renderers'), os.path.join(intermediate_dir, 'details', 'libs'), os.path.join(intermediate_dir, 'details', 'main-modules'), # Note: details/main-modules/display omitted intentionally, # since API links for those .RST files have been added manually. os.path.join(intermediate_dir, 'details', 'auxiliary-modules'), os.path.join(intermediate_dir, 'details', 'widgets') ) t2 = datetime.now() print('Example/API run time: ' + str(t2 - t1)) # --------------------------------------------------------------------- # Build PDF # --------------------------------------------------------------------- if not build_latex: print("Skipping Latex build.") else: t1 = datetime.now() print("****************") print("Building Latex output...") print("****************") # If PDF link is present in top index.rst, remove it so PDF # does not have a link to itself. with open(top_index_file, 'rb') as f: index_data = f.read().decode('utf-8') if pdf_link_ref_str in index_data: index_data = index_data.replace(pdf_link_ref_str, '') with open(top_index_file, 'wb') as f: f.write(index_data.encode('utf-8')) src = intermediate_dir dst = output_dir cpu = os.cpu_count() # As of 22-Feb-2025, sadly the -D version=xxx is not working as documented. # So the version strings applicable to Latex/PDF/man pages/texinfo # formats are assembled by `conf.py`. cmd_line = f'sphinx-build -M latex "{src}" "{dst}" -j {cpu}' cmd(cmd_line) # Generate PDF. print("****************") print("Building PDF...") print("****************") cmd_line = 'latexmk -pdf "LVGL.tex"' cmd(cmd_line, latex_output_dir, False) # Move resulting PDF to its output directory. if not os.path.exists(pdf_output_dir): os.makedirs(pdf_output_dir) shutil.move(pdf_src_file, pdf_dst_file) t2 = datetime.now() print('PDF : ' + pdf_dst_file) print('Latex gen time: ' + str(t2 - t1)) # --------------------------------------------------------------------- # Build HTML # --------------------------------------------------------------------- if not build_html: print("Skipping HTML build.") else: t1 = datetime.now() print("****************") print("Building HTML output...") print("****************") # If PDF is present in build directory, copy it to # intermediate directory for use by HTML build. # (Sphinx copies it to its HTML output, so it ends # up on the webserver where it can be downloaded). if os.path.isfile(pdf_dst_file): # Create _static/download/ directory if needed. if not os.path.exists(pdf_intermediate_dst_dir): os.makedirs(pdf_intermediate_dst_dir) shutil.copyfile(pdf_dst_file, pdf_intermediate_dst_file) # If PDF is present, ensure there is a link to it in the top # index.rst so HTML build will have it. # Support both Windows and Linux platforms with `os.linesep`. if os.path.isfile(pdf_intermediate_dst_file): with open(top_index_file, 'rb') as f: index_data = f.read().decode('utf-8') if pdf_link_ref_str not in index_data: index_data = cfg_pdf_link_ref_block_str + index_data with open(top_index_file, 'wb') as f: f.write(index_data.encode('utf-8')) # Note: While it can be done (e.g. if one needs to set a stop point # in Sphinx code for development purposes), it is NOT a good idea to # run Sphinx from script as # from sphinx.cmd.build import main as sphinx_build # sphinx_args = [...] # sphinx_build(sphinx_args) # because it takes ~10X longer to run than `sphinx_build` executable, # literally > 3 hours. ver = lvgl_version(version_src_file) src = intermediate_dir dst = output_dir cpu = os.cpu_count() # As of 22-Feb-2025, sadly the -D version=xxx is not working as documented. # So the version strings applicable to Latex/PDF/man pages/texinfo # formats are assembled by `conf.py`. The -D option in the command # line may go away if it does not, in fact, create some impact on # the doc-gen process. cmd_line = f'sphinx-build -M html "{src}" "{dst}" -D version="{ver}" {env_opt} -j {cpu}' cmd(cmd_line) t2 = datetime.now() print('HTML gen time : ' + str(t2 - t1)) # --------------------------------------------------------------------- # Indicate results. # --------------------------------------------------------------------- t_end = datetime.now() print('Total run time: ' + str(t_end - t0)) print('Done.') if __name__ == '__main__': """Make module importable as well as run-able.""" run(sys.argv[1:])