feat(docs): reorganize docs (#7136)
This commit is contained in:
Victor Wheeler
305
docs/build.py
305
docs/build.py
@@ -17,25 +17,113 @@ import tempfile
|
||||
import config_builder
|
||||
import add_translation
|
||||
|
||||
# due to the modifications that take place to the documentation files
|
||||
# -------------------------------------------------------------------------
|
||||
# Process args.
|
||||
#
|
||||
# Normal usage:
|
||||
# $ python build.py skip_latex
|
||||
#
|
||||
# Other optional arguments are meant for doc development to speed up
|
||||
# turn-around time between doc modification and seeing the final results:
|
||||
#
|
||||
# - skip_api
|
||||
# Skips generating API pages (this saves about 70% of build time).
|
||||
# This is intended to be used only during doc development to speed up
|
||||
# turn-around time between doc modifications and seeing final results.
|
||||
# - no_fresh_env
|
||||
# excludes -E command-line argument to `sphinx-build`, which forces
|
||||
# generating a whole new environment (memory of what was built
|
||||
# previously, forcing a full rebuild). "no_fresh_env" enables a
|
||||
# rebuild of only docs that got updated -- Sphinx's default behavior.
|
||||
# - develop
|
||||
# Leaves temporary directory intact for docs development purposes.
|
||||
# - fixed_tmp_dir
|
||||
# If (fixed_tmp_dir and 'LVGL_FIXED_TEMP_DIR' in os.environ),
|
||||
# then the temporary directory in the value of that environment
|
||||
# variable will be used instead of the normal (randomly-named)
|
||||
# temporary directory. This is important when getting `sphinx-build`
|
||||
# to ONLY rebuild updated documents, since changing the directory
|
||||
# from which they are generated (normally the randomly-named temp
|
||||
# dir) will force Sphinx to do a full-rebuild because it remembers
|
||||
# the doc paths from which the build was last generated.
|
||||
# - docs_dev
|
||||
# Forces "fresh_env" to False, and "fixed_tmp_dir" to True. This is
|
||||
# merely a shortcut to having both "no_fresh_env" and "fixed_tmp_dir"
|
||||
# on the command line.
|
||||
# - skip_trans
|
||||
# Skips adding translation links. This allows direct copying of
|
||||
# of .RST files to `temp_directory` when they are updated to save
|
||||
# time during re-build. Final build must not include this option
|
||||
# so that the translation links are added at the top of each page.
|
||||
#
|
||||
# With arguments [skip_latex, develop, docs_dev], Sphinx will generate
|
||||
# docs from a fixed temporary directory that can be then used later from
|
||||
# the LVGL ./docs/ directory like this:
|
||||
#
|
||||
# $ sphinx-build -b html "fixed_temp_dir" "..\out_html" -D version="9.3" -j cpu_count
|
||||
#
|
||||
# to only rebuild docs that have been updated.
|
||||
# -------------------------------------------------------------------------
|
||||
clean = 0
|
||||
skip_latex = False
|
||||
skip_api = False
|
||||
fresh_env = True
|
||||
develop = False
|
||||
fixed_tmp_dir = False
|
||||
docs_dev = False
|
||||
skip_trans = False
|
||||
args = sys.argv[1:]
|
||||
|
||||
if len(args) >= 1:
|
||||
if "clean" in args:
|
||||
clean = 1
|
||||
if "skip_latex" in args:
|
||||
skip_latex = True
|
||||
if 'skip_api' in args:
|
||||
skip_api = True
|
||||
if 'no_fresh_env' in args:
|
||||
fresh_env = False
|
||||
if 'develop' in args:
|
||||
develop = True
|
||||
if 'fixed_tmp_dir' in args:
|
||||
fixed_tmp_dir = True
|
||||
if 'docs_dev' in args:
|
||||
docs_dev = True
|
||||
if 'skip_trans' in args:
|
||||
skip_trans = True
|
||||
|
||||
# Arg ramifications...
|
||||
# docs_dev implies no fresh_env
|
||||
if docs_dev:
|
||||
fresh_env = False
|
||||
fixed_tmp_dir = True
|
||||
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# Due to the modifications that take place to the documentation files
|
||||
# when the documentation builds it is better to copy the source files to a
|
||||
# temporary folder and modify the copies. Not setting it up this way makes it
|
||||
# a real headache when making alterations that need to be committed as the
|
||||
# alterations trigger the files as changed.
|
||||
|
||||
# If there is debugging that needs to be done you can provide a command line
|
||||
# switch of "develop" and it will leave the temporary directory in tact and
|
||||
# that directory will be output at the end of the build.
|
||||
|
||||
# the html and PDF output locations are going to remain the same as they were.
|
||||
# alterations trigger the files as changed. Also, this keeps maintenance
|
||||
# effort to a minimum as adding a new language translation only needs to be
|
||||
# done in 2 places (add_translation.py and ./docs/_ext/link_roles.py) rather
|
||||
# than once for each .rst file.
|
||||
#
|
||||
# The html and PDF output locations are going to remain the same as they were.
|
||||
# it's just the source documentation files that are going to be copied.
|
||||
# -------------------------------------------------------------------------
|
||||
if fixed_tmp_dir and 'LVGL_FIXED_TEMP_DIR' in os.environ:
|
||||
temp_directory = os.environ['LVGL_FIXED_TEMP_DIR']
|
||||
else:
|
||||
temp_directory = tempfile.mkdtemp(suffix='.lvgl_docs')
|
||||
|
||||
temp_directory = tempfile.mkdtemp(suffix='.lvgl_docs')
|
||||
print(f'Using temp directory: [{temp_directory}]')
|
||||
|
||||
langs = ['en']
|
||||
|
||||
# Change to script directory for consistency
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# Set up paths.
|
||||
# -------------------------------------------------------------------------
|
||||
base_path = os.path.abspath(os.path.dirname(__file__))
|
||||
project_path = os.path.abspath(os.path.join(base_path, '..'))
|
||||
examples_path = os.path.join(project_path, 'examples')
|
||||
@@ -48,24 +136,14 @@ pdf_dst_file = os.path.join(temp_directory, 'LVGL.pdf')
|
||||
html_src_path = temp_directory
|
||||
html_dst_path = os.path.join(project_path, 'out_html')
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# Change to script directory for consistency.
|
||||
# -------------------------------------------------------------------------
|
||||
os.chdir(base_path)
|
||||
|
||||
|
||||
clean = 0
|
||||
trans = 0
|
||||
skip_latex = False
|
||||
develop = False
|
||||
args = sys.argv[1:]
|
||||
|
||||
if len(args) >= 1:
|
||||
if "clean" in args:
|
||||
clean = 1
|
||||
if "skip_latex" in args:
|
||||
skip_latex = True
|
||||
if 'develop' in args:
|
||||
develop = True
|
||||
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# Provide a way to run an external command and abort build on error.
|
||||
# -------------------------------------------------------------------------
|
||||
def cmd(s, start_dir=None):
|
||||
if start_dir is None:
|
||||
start_dir = os.getcwd()
|
||||
@@ -79,18 +157,32 @@ def cmd(s, start_dir=None):
|
||||
os.chdir(saved_dir)
|
||||
|
||||
if result != 0:
|
||||
print("Exit build due to previous error")
|
||||
print("Exiting build due to previous error.")
|
||||
sys.exit(result)
|
||||
|
||||
|
||||
# Get the current branch name
|
||||
# -------------------------------------------------------------------------
|
||||
# Get current branch name
|
||||
# -------------------------------------------------------------------------
|
||||
# 03-Oct-2024: Gabor requested this 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. This gets used in the
|
||||
# 'Edit on GitHub' links in the upper-right corner of pages.
|
||||
# Original code:
|
||||
# status, br = subprocess.getstatusoutput("git branch --show-current")
|
||||
# _, gitcommit = subprocess.getstatusoutput("git rev-parse HEAD")
|
||||
# br = re.sub(r'\* ', '', br)
|
||||
status, br = subprocess.getstatusoutput("git branch --show-current")
|
||||
_, gitcommit = subprocess.getstatusoutput("git rev-parse HEAD")
|
||||
br = re.sub(r'\* ', '', br)
|
||||
|
||||
# If in an unusual branch that is not 'master' or 'release/...'
|
||||
# then default to 'master'.
|
||||
if '/' in br and 'release' not in br:
|
||||
br = 'master'
|
||||
|
||||
gitcommit = br
|
||||
urlpath = re.sub('release/', '', br)
|
||||
|
||||
# These environment variables are used in other scripts.
|
||||
os.environ['LVGL_URLPATH'] = urlpath
|
||||
os.environ['LVGL_GITCOMMIT'] = gitcommit
|
||||
|
||||
@@ -101,8 +193,9 @@ print("****************")
|
||||
print("Building")
|
||||
print("****************")
|
||||
|
||||
# Remove all previous output files if 'clean' on command line.
|
||||
if clean:
|
||||
print('cleaning...')
|
||||
print('Removing previous output files...')
|
||||
# api_path = os.path.join(dname, 'API')
|
||||
# xml_path = os.path.join(dname, 'xml')
|
||||
# doxy_path = os.path.join(dname, 'doxygen_html')
|
||||
@@ -125,11 +218,21 @@ if clean:
|
||||
# os.mkdir(api_path)
|
||||
# os.mkdir(lang)
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# Build local lv_conf.h from lv_conf_template.h for this build only.
|
||||
# -------------------------------------------------------------------------
|
||||
config_builder.run()
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# Copy files to 'temp_directory' where they will be edited
|
||||
# (translation link and API links) before being used to generate new docs.
|
||||
# -------------------------------------------------------------------------
|
||||
shutil.copytree('.', temp_directory, dirs_exist_ok=True)
|
||||
shutil.copytree(examples_path, os.path.join(temp_directory, 'examples'))
|
||||
shutil.copytree(examples_path, os.path.join(temp_directory, 'examples'), dirs_exist_ok=True)
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# Replace tokens in Doxyfile in 'temp_directory' with data from this run.
|
||||
# -------------------------------------------------------------------------
|
||||
with open(os.path.join(temp_directory, 'Doxyfile'), 'rb') as f:
|
||||
data = f.read().decode('utf-8')
|
||||
|
||||
@@ -139,35 +242,69 @@ data = data.replace('*#*#SRC#*#*', '"{0}"'.format(lvgl_src_path))
|
||||
with open(os.path.join(temp_directory, 'Doxyfile'), 'wb') as f:
|
||||
f.write(data.encode('utf-8'))
|
||||
|
||||
|
||||
print("Generate the list of examples")
|
||||
# -------------------------------------------------------------------------
|
||||
# Generate examples pages.
|
||||
# -------------------------------------------------------------------------
|
||||
print("Generating examples...")
|
||||
ex.exec(temp_directory)
|
||||
|
||||
print("Add translation")
|
||||
add_translation.exec(temp_directory)
|
||||
if skip_trans:
|
||||
print("Skipping translation links as requested.")
|
||||
else:
|
||||
# ---------------------------------------------------------------------
|
||||
# Add translation links at top of all .rst files.
|
||||
# ---------------------------------------------------------------------
|
||||
print("Adding translation links...")
|
||||
add_translation.exec(temp_directory)
|
||||
|
||||
print("Running doxygen")
|
||||
cmd('doxygen Doxyfile', temp_directory)
|
||||
if skip_api:
|
||||
print("Skipping API generation as requested.")
|
||||
else:
|
||||
# ---------------------------------------------------------------------
|
||||
# Generate API pages and links thereto.
|
||||
# ---------------------------------------------------------------------
|
||||
print("Running Doxygen...")
|
||||
cmd('doxygen Doxyfile', temp_directory)
|
||||
print("Generating API documentation .RST files...")
|
||||
|
||||
print('Reading Doxygen output')
|
||||
doc_builder.EMIT_WARNINGS = False
|
||||
|
||||
doc_builder.EMIT_WARNINGS = False
|
||||
# Create .RST files for API pages.
|
||||
doc_builder.run(
|
||||
project_path,
|
||||
temp_directory,
|
||||
os.path.join(temp_directory, 'intro'),
|
||||
os.path.join(temp_directory, 'intro', 'add-lvgl-to-your-project'),
|
||||
os.path.join(temp_directory, 'details'),
|
||||
os.path.join(temp_directory, 'details', 'base-widget'),
|
||||
os.path.join(temp_directory, 'details', 'base-widget', 'layouts'),
|
||||
os.path.join(temp_directory, 'details', 'base-widget', 'styles'),
|
||||
os.path.join(temp_directory, 'details', 'debugging'),
|
||||
os.path.join(temp_directory, 'details', 'integration'),
|
||||
os.path.join(temp_directory, 'details', 'integration', 'bindings'),
|
||||
os.path.join(temp_directory, 'details', 'integration', 'building'),
|
||||
os.path.join(temp_directory, 'details', 'integration', 'chip'),
|
||||
os.path.join(temp_directory, 'details', 'integration', 'driver'),
|
||||
os.path.join(temp_directory, 'details', 'integration', 'driver', 'display'),
|
||||
os.path.join(temp_directory, 'details', 'integration', 'driver', 'touchpad'),
|
||||
os.path.join(temp_directory, 'details', 'integration', 'framework'),
|
||||
os.path.join(temp_directory, 'details', 'integration', 'ide'),
|
||||
os.path.join(temp_directory, 'details', 'integration', 'os'),
|
||||
os.path.join(temp_directory, 'details', 'integration', 'os', 'yocto'),
|
||||
os.path.join(temp_directory, 'details', 'integration', 'renderers'),
|
||||
os.path.join(temp_directory, 'details', 'libs'),
|
||||
os.path.join(temp_directory, 'details', 'main-components'),
|
||||
os.path.join(temp_directory, 'details', 'other-components'),
|
||||
os.path.join(temp_directory, 'details', 'widgets')
|
||||
)
|
||||
|
||||
doc_builder.run(
|
||||
project_path,
|
||||
temp_directory,
|
||||
os.path.join(temp_directory, 'layouts'),
|
||||
os.path.join(temp_directory, 'libs'),
|
||||
os.path.join(temp_directory, 'others'),
|
||||
os.path.join(temp_directory, 'overview'),
|
||||
os.path.join(temp_directory, 'overview', 'renderers'),
|
||||
os.path.join(temp_directory, 'porting'),
|
||||
os.path.join(temp_directory, 'widgets')
|
||||
)
|
||||
print('Reading Doxygen output...')
|
||||
|
||||
# we make sure to remove the link to the PDF before the PDF get generated
|
||||
# -------------------------------------------------------------------------
|
||||
# We make sure to remove the link to the PDF before the PDF get generated
|
||||
# doesn't make any sense to have a link to the PDF in the PDF. The link gets
|
||||
# added if there is a PDF build so the HTML build will have the link.
|
||||
# -------------------------------------------------------------------------
|
||||
index_path = os.path.join(temp_directory, 'index.rst')
|
||||
|
||||
with open(index_path, 'rb') as f:
|
||||
@@ -181,11 +318,12 @@ if 'PDF version: :download:`LVGL.pdf <LVGL.pdf>`' in index_data:
|
||||
with open(index_path, 'wb') as f:
|
||||
f.write(index_data.encode('utf-8'))
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# BUILD PDF
|
||||
# -------------------------------------------------------------------------
|
||||
if skip_latex:
|
||||
print("skipping latex build as requested")
|
||||
print("Skipping latex build as requested.")
|
||||
else:
|
||||
|
||||
# Silly workaround to include the more or less correct
|
||||
# PDF download link in the PDF
|
||||
# cmd("cp -f " + lang +"/latex/LVGL.pdf LVGL.pdf | true")
|
||||
@@ -212,9 +350,10 @@ else:
|
||||
with open(index_path, 'wb') as f:
|
||||
f.write(index_data.encode('utf-8'))
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# BUILD HTML
|
||||
# This version of get_version() works correctly under Windows and Linux.
|
||||
# Credit: @kdschlosser
|
||||
# -------------------------------------------------------------------------
|
||||
# This version of get_version() also works correctly under Windows.
|
||||
def get_version():
|
||||
path = os.path.join(project_path, 'lv_version.h')
|
||||
with open(path, 'rb') as fle:
|
||||
@@ -230,17 +369,39 @@ def get_version():
|
||||
|
||||
return f'{major.strip()}.{minor.strip()}'
|
||||
|
||||
|
||||
cmd('sphinx-build -b html "{src}" "{dst}" -D version="{version}" -E -j {cpu}'.format(
|
||||
src=html_src_path,
|
||||
dst=html_dst_path,
|
||||
version=get_version(),
|
||||
cpu=os.cpu_count()
|
||||
))
|
||||
|
||||
if develop:
|
||||
print('temp directory:', temp_directory)
|
||||
# -------------------------------------------------------------------------
|
||||
# Run Sphinx after determining whether to use -E (fresh environment)
|
||||
# command-line argument.
|
||||
# -------------------------------------------------------------------------
|
||||
if fresh_env:
|
||||
# Uses -E option (same as --fresh-env). Forces sphinx-build to rebuild sphinx
|
||||
# environment so that all docs are fully regenerated, even if they have not changed.
|
||||
print("Regenerating all files...")
|
||||
cmd('sphinx-build -b html "{src}" "{dst}" -D version="{version}" -E -j {cpu}'.format(
|
||||
src=html_src_path,
|
||||
dst=html_dst_path,
|
||||
version=get_version(),
|
||||
cpu=os.cpu_count()
|
||||
))
|
||||
else:
|
||||
# Does not use -E option (same as --fresh-env).
|
||||
print("Regenerating only updated files...")
|
||||
cmd('sphinx-build -b html "{src}" "{dst}" -D version="{version}" -j {cpu}'.format(
|
||||
src=html_src_path,
|
||||
dst=html_dst_path,
|
||||
version=get_version(),
|
||||
cpu=os.cpu_count()
|
||||
))
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# If 'develop' was specified on command line, announce location of temp dir.
|
||||
# Otherwise, remove temporary files created for the doc build.
|
||||
# -------------------------------------------------------------------------
|
||||
if develop:
|
||||
print('Temp directory: ', temp_directory)
|
||||
else:
|
||||
print('Removing temporary files...', temp_directory)
|
||||
# Recursively remove generated files in `temp_directory`.
|
||||
def iter_temp(p):
|
||||
folders = []
|
||||
remove_folder = True
|
||||
@@ -268,7 +429,13 @@ else:
|
||||
|
||||
iter_temp(temp_directory)
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# Remove temporary `lv_conf.h` created for this build.
|
||||
# -------------------------------------------------------------------------
|
||||
config_builder.cleanup()
|
||||
|
||||
print('output path:', html_dst_path)
|
||||
print('\nFINISHED!!')
|
||||
# -------------------------------------------------------------------------
|
||||
# Indicate results.
|
||||
# -------------------------------------------------------------------------
|
||||
print('Output path: ', html_dst_path)
|
||||
print('Finished.')
|
||||
|
||||
Reference in New Issue
Block a user