Lines Matching +full:- +full:- +full:exit +full:- +full:code
9 - Doxygen (to generate LVGL API XML), then
10 - Sphinx
14 Sphinx documentation. It also supported a command-line option `clean`
20 - Using environment variables to convey branch names to several more
21 places where they are used in the docs-generating process (instead
22 of re-writing writing `conf.py` and a `header.rst` each time docs
25 - Supporting additional command-line options.
27 - Generating a temporary `./docs/lv_conf.h` for Doxygen to use
30 - Supporting multiple execution platforms (which then required tokenizing
31 Doxygen's INPUT path in `Doxyfile` and re-writing portions that used
34 - Adding translation and API links (requiring generating docs in a
38 - Generating EXAMPLES page + sub-examples where applicable to individual
39 documents, e.g. to widget-, style-, layout-pages, etc.
41 - Building PDF via latex (when working).
44 Command-Line Arguments
45 ----------------------
46 Command-line arguments have been broken down to give the user the
48 this script. These were added to speed up long doc-development
49 tasks by shortening the turn-around time between doc modification
52 only modify changed documents, and reduce an average ~22-minute
58 ------------
64 Docs-Dev Initial Docs Generation Usage
65 --------------------------------------
76 Docs-Dev Update-Only Generation Usage
77 -------------------------------------
79 run the following until docs-development task is complete.
86 +--------------+------------+---------------------------------+
90 +--------------+------------+---------------------------------+
92 +--------------+------------+---------------------------------+
94 +--------------+------------+---------------------------------+
96 +--------------+------------+---------------------------------+
99 Sphinx Doc-Regeneration Criteria
100 --------------------------------
103 - source-doc modification date
104 - Change the modification date and `sphinx-build` will re-build it.
106 - full (absolute) path to the source document, including its file name
107 - Change the path or filename and `sphinx-build` will re-build it.
109 - whether the -E option is on the `sphinx-build` command line
110 - -E forces `sphinx-build` to do a full re-build.
114 ---------------------
115 - skip_latex
118 - skip_api
121 turn-around time between doc modifications and seeing final results.
122 - no_fresh_env
123 Excludes -E command-line argument to `sphinx-build`, which, when present,
126 of only docs that got updated -- Sphinx's default behavior.
127 - preserve (previously "develop")
129 - fixed_tmp_dir
132 to populate `temp_directory` instead of the normal (randomly-named)
133 temporary directory. This is important when getting `sphinx-build`
135 from which they are generated (normally the randomly-named temp
136 dir) will force Sphinx to do a full-rebuild because it remembers
138 - skip_trans
141 during re-build. Final build must not include this option so that
143 - no_copy
146 - fixed_tmp_dir == True, and
147 - the doc files were previously copied to the temporary directory
149 - docs_dev
150 This is a command-line shortcut to combining these command-line args:
151 - no_fresh_env
152 - preserve
153 - fixed_tmp_dir
154 - no_copy
155 - update
157 and re-copy the updated `./docs/` files to the temporary directory
160 Warning: this wipes out translation links and API-page links that
162 development -- not for final doc generation.
166 # IMPORTANT: If you are getting a PDF-lexer error for an example, check
189 # ---------------------------------------------------------------------
191 # ---------------------------------------------------------------------
195 # ---------------------------------------------------------------------
202 # ---------------------------------------------------------------------
217 # We use chained `if-elif-else` instead of `match` for those on Linux
241 exit(1)
251 # ---------------------------------------------------------------------
263 # ---------------------------------------------------------------------
271 # ---------------------------------------------------------------------
273 # ---------------------------------------------------------------------
284 # ---------------------------------------------------------------------
286 # ---------------------------------------------------------------------
289 # ---------------------------------------------------------------------
291 # ---------------------------------------------------------------------
300 print("-------------------------------------")
306 sys.exit(result)
308 # ---------------------------------------------------------------------
310 # - LVGL_URLPATH <= 'master' or '8.4' '9.2' etc.
311 # - LVGL_GITCOMMIT <= same (see 03-Oct-2024 note below).
313 # These supply input later in the doc-generation process as follows:
316 # - `conf.py` to build `html_baseurl` for Sphinx for
317 # - generated index
318 # - generated search window
319 # - establishing canonical page for search engines
320 # - `link_roles.py` to generate translation links
321 # - `doc_builder.py` to generate links to API pages
324 # - `conf.py` => html_context['github_version'] for
325 # Sphinx Read-the-Docs theme to add to [Edit on GitHub] links
326 # - `conf.py` => repo_commit_hash for generated EXAMPLES pages for:
327 # - [View on GitHub] buttons (view C code examples)
328 # - [View on GitHub] buttons (view Python code examples)
329 # ---------------------------------------------------------------------
330 # 03-Oct-2024: Gabor requested LVGL_GITCOMMIT be changed to a branch
334 # - [Edit on GitHub] links in doc pages (via Sphinx theme), and
335 # - [View on GitHub] links in example pages (via `example_list.py`
337 # Original code:
338 # status, br = subprocess.getstatusoutput("git branch --show-current")
339 # _, gitcommit = subprocess.getstatusoutput("git rev-parse HEAD")
343 # This is no longer needed with `--show-current` option now used.
344 # ---------------------------------------------------------------------
345 status, branch = subprocess.getstatusoutput("git branch --show-current")
364 # ---------------------------------------------------------------------
365 # Start doc-build process.
366 # ---------------------------------------------------------------------
375 # The below commented-out code below is being preserved
376 # for docs-generation development purposes.
401 # ---------------------------------------------------------------------
403 # ---------------------------------------------------------------------
406 # ---------------------------------------------------------------------
409 # ---------------------------------------------------------------------
435 # ---------------------------------------------------------------------
438 # ---------------------------------------------------------------------
456 # ---------------------------------------------------------------------
458 # ---------------------------------------------------------------------
461 data = f.read().decode('utf-8')
467 f.write(data.encode('utf-8'))
469 # -----------------------------------------------------------------
470 # Generate examples pages. Include sub-pages pages that get included
472 # -----------------------------------------------------------------
476 # -----------------------------------------------------------------
478 # -----------------------------------------------------------------
485 # ---------------------------------------------------------------------
487 # ---------------------------------------------------------------------
501 os.path.join(temp_directory, 'intro', 'add-lvgl-to-your-project'),
503 os.path.join(temp_directory, 'details', 'base-widget'),
504 os.path.join(temp_directory, 'details', 'base-widget', 'layouts'),
505 os.path.join(temp_directory, 'details', 'base-widget', 'styles'),
520 os.path.join(temp_directory, 'details', 'main-components'),
521 os.path.join(temp_directory, 'details', 'other-components'),
527 # ---------------------------------------------------------------------
529 # ---------------------------------------------------------------------
537 index_data = f.read().decode('utf-8')
545 f.write(index_data.encode('utf-8'))
549 # cmd("cp -f " + lang +"/latex/LVGL.pdf LVGL.pdf | true")
553 cmd_line = f'sphinx-build -b latex "{src}" "{dst}" -j {cpu}'
557 cmd_line = 'latexmk -pdf "LVGL.tex"'
568 f.write(index_data.encode('utf-8'))
570 # ---------------------------------------------------------------------
572 # ---------------------------------------------------------------------
596 # Exit early if we have both values.
603 # in Sphinx code for development purposes), it is NOT a good idea to
611 # '-E' option forces Sphinx to rebuild its environment so all docs are
616 env_opt = '-E'
625 cmd_line = f'sphinx-build -b html "{src}" "{dst}" -D version="{ver}" {env_opt} -j {cpu}'
631 print('Sphinx run time: ' + str(t3 - t2))
633 # ---------------------------------------------------------------------
635 # ---------------------------------------------------------------------
643 # ---------------------------------------------------------------------
645 # ---------------------------------------------------------------------
648 # ---------------------------------------------------------------------
650 # ---------------------------------------------------------------------
652 print('Total run time: ' + str(t4 - t1))
661 # -------------------------------------------------------------------------
662 # Make module importable as well as run-able.
663 # -------------------------------------------------------------------------