docs: Enable page redirection for old links

Author: Gao Wei

.gitignore

@@ -28,6 +28,7 @@ examples/**/managed_components
 examples/**/dependencies.lock
 
 # Doc build artifacts
+docs/_build/
 docs/*/_build/
 docs/*/doxygen-warning-log.txt
 docs/*/sphinx-warning-log.txt

docs/ADF_TEMPLATE_EXAMPLE_README_EN.md

@@ -1,4 +1,4 @@
-_Note that this is a template for an ESP-ADF example README.md file. When using this template, replace all these emphasised placeholders with example-specific content._
+_Note that this is a template for an ESP-ADF example README.md file. When using this template, replace all the emphasized placeholders (in italics) with example-specific content._
 
 # _Example Title_
 
@@ -124,7 +124,7 @@ _Command to build the example_
 _Command to flash the example_
 
 - Legacy GNU Make command: `make flash monitor`
-- CMake command: `idf.py -p PORT flash monitor`
+- CMake command: `idf.py build flash monitor`
 
 For full steps to configure and build an ESP-IDF project, please go to [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html) and select the chip and version in the upper left corner of the page.
 

docs/README.md

@@ -11,14 +11,24 @@ Use actual documentation generated within about 20 minutes on each commit:
 * English: https://docs.espressif.com/projects/esp-adf/en/latest/
 * 中文: https://docs.espressif.com/projects/esp-adf/zh_CN/latest/
 
-The above URLs are all for the master branch latest version. Click the drop-down in the bottom left to choose a stable version or to download a PDF.
+The above URLs are all for the master branch latest version. Click on the link in the bottom right corner to download the PDF version.
 
 
 # Building Documentation
 
-* Install `make` and `doxygen` for your platform (`make` may already be installed as an ESP-IDF prerequisite).
-* Change to either the docs/en or docs/zh_CN subdirectory and run `make html`
-* `make` will probably prompt you to run a python pip install step to get some other Python-related prerequisites. Run the command as shown, then re-run `make html` to build the docs.
+The documentation is built using the python package `esp-docs`, which can be installed by running:
+
+```
+pip install esp-docs
+```
+
+For a summary of available options, run:
+
+```
+build-docs --help
+```
+
+For more information, see [ESP-Docs User Guide](https://docs.espressif.com/projects/esp-docs/en/latest/).
 
 ## For MSYS2 MINGW32 on Windows
 

docs/conf_common.py

@@ -1,3 +1,4 @@
+import re
 import sys, os
 from esp_docs.conf_docs import *  # noqa: F403,F401
 from local_util import run_cmd_get_output, copy_if_modified
@@ -28,6 +29,14 @@
                'esp_docs.esp_extensions.run_doxygen',
                ]
 
+# Custom added feature to allow redirecting old URLs
+with open('../page_redirects.txt') as f:
+    lines = [re.sub(' +', ' ', line.strip()) for line in f.readlines() if line.strip() != '' and not line.startswith('#')]
+    for line in lines:  # check for well-formed entries
+        if len(line.split(' ')) != 2:
+            raise RuntimeError('Invalid line in page_redirects.txt: %s' % line)
+html_redirect_pages = [tuple(line.split(' ')) for line in lines]
+
 # Disable format_esp_target
 extensions.remove('esp_docs.esp_extensions.format_esp_target')