OVMS3-idf/docs/local_util.py
Ivan Grokhotkov 2e0f8b5a70 docs: speed up incremental builds
On each documentation build (‘make html’), doxygen regenerates XML
files. In addition to that, gen-dxd.py regenerates API reference
files under _build/inc/. This results in Sphinx flagging about half
of the input files as modified, and incremental builds taking long
time.

With this change, XML files generated by Doxygen are copied into
docs/xml_in directory only when they are changed. Breathe is pointed
to docs/xml_in directory instead of docs/xml. In addition to that,
gen-dxd.py is modified to only write to the output file when contents
change.

Overall, incremental build time (with no source files changed) is
reduced from ~7 minutes to ~8 seconds (on a particular OS X
computer).

Due to the way Breathe includes Doxygen XML files, there is still
going to be a massive rebuild every time functions, enums, macros,
structures are added or removed from the header files scanned
by Doxygen, but at least individual .rst files can be edited
at a much faster pace.
2018-03-07 17:45:15 +08:00

53 lines
1.8 KiB
Python

# Utility functions used in conf.py
#
# Copyright 2017 Espressif Systems (Shanghai) PTE LTD
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http:#www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
import re
import os
import shutil
def run_cmd_get_output(cmd):
return os.popen(cmd).read().strip()
def files_equal(path_1, path_2):
if not os.path.exists(path_1) or not os.path.exists(path_2):
return False
file_1_contents = ''
with open(path_1, "r") as f_1:
file_1_contents = f_1.read()
file_2_contents = ''
with open(path_2, "r") as f_2:
file_2_contents = f_2.read()
return file_1_contents == file_2_contents
def copy_file_if_modified(src_file_path, dst_file_path):
if not files_equal(src_file_path, dst_file_path):
dst_dir_name = os.path.dirname(dst_file_path)
if not os.path.isdir(dst_dir_name):
os.makedirs(dst_dir_name)
shutil.copy(src_file_path, dst_file_path)
def copy_if_modified(src_path, dst_path):
if os.path.isfile(src_path):
copy_file_if_modified(src_path, dst_path)
return
src_path_len = len(src_path)
for root, dirs, files in os.walk(src_path):
for src_file_name in files:
src_file_path = os.path.join(root, src_file_name)
dst_file_path = os.path.join(dst_path + root[src_path_len:], src_file_name)
copy_file_if_modified(src_file_path, dst_file_path)