[PATCH v2 0/3] doc: build on Windows

[Varghese, Vipin]

[AMD Official Use Only - General]

Hi Dmitry,

Thank you for allowing me to try these changes on both Linux & Windows. I was facing some hurdles in both environments.

On Linux I was facing
```
	Traceback (most recent call last):
  File "/home/amd/vipin/dpdk/test/dpdk/doc/api/generate_doxygen.py", line 13, in <module>
    subprocess.run(doxygen_command, check=True, stdout=out)
  File "/usr/lib/python3.8/subprocess.py", line 493, in run
    with Popen(*popenargs, **kwargs) as process:
  File "/usr/lib/python3.8/subprocess.py", line 858, in __init__
    self._execute_child(args, executable, preexec_fn, close_fds,
  File "/usr/lib/python3.8/subprocess.py", line 1580, in _execute_child
    executable = args[0]
IndexError: list index out of range
```

With some debugging this was root caused to `doxygen permission issue in the environment`. Re-running the `ninja -C build` with root user solved this for me.

For Windows I faced

```
[528/682] Generating doc/guides/html_guides with a custom command
FAILED: doc/guides/html
"C:\Program Files\Meson\meson.exe" "runpython" "../buildtools/call-sphinx-build.py" "C:/Users/Administrator/AppData/Local/Programs/Python/Python310/Scripts/sphinx-build.EXE" "22.07.0-rc0" "C:/Users/Administrator/Desktop/docs/doc/guides" "C:/Users/Administrator/Desktop/docs/build/doc/guides"
Traceback (most recent call last):
  File "mesonbuild\mesonmain.py", line 146, in run
  File "mesonbuild\mesonmain.py", line 106, in run_runpython_command
  File "runpy.py", line 269, in run_path
  File "runpy.py", line 96, in _run_module_code
  File "runpy.py", line 86, in _run_code
  File "../buildtools/call-sphinx-build.py", line 10, in <module>
    from packaging.version import Version
ModuleNotFoundError: No module named 'packaging'

ERROR: Unhandled python exception
```

Checking for `packaging` in windows, the library is present
```
C:\Users\Administrator\Desktop\docs>pip3 install packaging
Requirement already satisfied: packaging in c:\users\administrator\appdata\local\programs\python\python310\lib\site-packages (21.3)
Requirement already satisfied: pyparsing!=3.0.5,>=2.0.2 in c:\users\administrator\appdata\local\programs\python\python310\lib\site-packages (from packaging) (3.0.7)
```

Running python directly gives success for package as
```
import packaging
dir(packaging)
['__about__', '__all__', '__author__', '__builtins__', '__cached__', '__copyright__', '__doc__', '__email__', '__file__', '__license__', '__loader__', '__name__', '__package__', '__path__', '__spec__', '__summary__', '__title__', '__uri__', '__version__']
```

So the problem is narrowed down `sys.path` variation as

```
Path from standalone run for call-sphinx-build.py: ['C:\\Users\\Administrator\\Desktop\\docs\\buildtools', 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python310\\python310.zip', 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python310\\DLLs', 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python310\\lib', 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python310', 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python310\\lib\\site-packages']

Path from ninja build for docs for call-sphinx-build.py: ['../buildtools', 'C:\\Program Files\\Meson\\base_library.zip', 'C:\\Program Files\\Meson\\lib-dynload', 'C:\\Program Files\\Meson']
```

> -----Original Message-----
> From: Dmitry Kozlyuk <dmitry.kozliuk at gmail.com>
> Sent: Wednesday, April 6, 2022 10:40 PM
> To: dev at dpdk.org
> Cc: Varghese, Vipin <Vipin.Varghese at amd.com>; Dmitry Kozlyuk
> <dmitry.kozliuk at gmail.com>
> Subject: [PATCH v2 0/3] doc: build on Windows
> 
> [CAUTION: External Email]
> 
> Enable biulding documentation on Windows natively.
> Thanks to Vipin for raising the issue.
> 
> v2: fix typo in meson.build file name,
>     use print(file=x) instead of stdout redirection.
> 
> Dmitry Kozlyuk (3):
>   doc: simplify CSS customization for Doxygen
>   doc: fix API index Markdown syntax
>   doc: rewrite shell scripts in Python
> 
>  doc/api/custom.css           |   6 +
>  doc/api/doxy-api-index.md    | 366 +++++++++++++++++------------------
>  doc/api/doxy-api.conf.in     |   1 +
>  doc/api/doxy-html-custom.sh  |   8 -
>  doc/api/generate_doxygen.py  |  19 ++
>  doc/api/generate_doxygen.sh  |  15 --
>  doc/api/generate_examples.py |  31 +++
>  doc/api/generate_examples.sh |  20 --
>  doc/api/meson.build          |   7 +-
>  9 files changed, 243 insertions(+), 230 deletions(-)  create mode 100644
> doc/api/custom.css  delete mode 100755 doc/api/doxy-html-custom.sh  create
> mode 100644 doc/api/generate_doxygen.py  delete mode 100755
> doc/api/generate_doxygen.sh  create mode 100644
> doc/api/generate_examples.py  delete mode 100755
> doc/api/generate_examples.sh
> 
> --
> 2.29.3