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

  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
  

[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@gmail.com>
> Sent: Wednesday, April 6, 2022 10:40 PM
> To: dev@dpdk.org
> Cc: Varghese, Vipin <Vipin.Varghese@amd.com>; Dmitry Kozlyuk
> <dmitry.kozliuk@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
  

Hi Vipin,

2022-05-11 09:34 (UTC+0000), Varghese, Vipin:
> 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
> ```
[...]
> 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']
> ```

Thanks for testing.
The Linux issue seems to be exclusively related to you environment.
For the Windows issue: I have both Meson and Sphinx installed via pip3,
your setup seems to have Meson installed separately and using its own Python.
Bruce, can you advise if Python tools are supposed to work
when Meson's Python is different from the system Python?
  

> Dmitry Kozlyuk (3):
>   doc: simplify CSS customization for Doxygen
>   doc: fix API index Markdown syntax
>   doc: rewrite shell scripts in Python

Applied, thanks.

I hope the Windows setup issue seen by Vipin can be workarounded.