Failed to build doc for pyside6 in qch by following the doc

jronald

The doc for build doc for pyside6 seems outdated:
https://doc.qt.io/qtforpython-6/gettingstarted.html#building-the-documentation

$ pip install -r requirements.txt
...
$ pip install graphviz sphinx_tabs
... (conflict: sphinx-tabs depends on sphinx 5.3.0, but sphix-panels depends on sphinx 4.5.0)
$ pip list
Package                       Version
----------------------------- -----------
alabaster                     0.7.12
altgraph                      0.17.3
Babel                         2.11.0
beautifulsoup4                4.11.1
build                         0.7.0
certifi                       2022.9.24
charset-normalizer            2.1.1
distro                        1.8.0
docutils                      0.18.1
furo                          2022.9.29
graphviz                      0.20.1
idna                          3.4
imagesize                     1.4.1
Jinja2                        3.1.2
MarkupSafe                    2.1.1
Nuitka                        1.1.7
numpy                         1.23.4
packaging                     21.3
pep517                        0.13.0
pip                           22.3
Pygments                      2.13.0
PyInstaller                   3.6
PyOpenGL                      3.1.6
pyparsing                     3.0.9
pytz                          2022.6
requests                      2.28.1
setuptools                    63.2.0
six                           1.16.0
snowballstemmer               2.2.0
soupsieve                     2.3.2.post1
Sphinx                        5.3.0
sphinx-basic-ng               1.0.0b1
sphinx-copybutton             0.5.0
sphinx-panels                 0.6.0
sphinx-tabs                   3.4.1
sphinxcontrib-applehelp       1.0.2
sphinxcontrib-devhelp         1.0.2
sphinxcontrib-htmlhelp        2.0.0
sphinxcontrib-jsmath          1.0.1
sphinxcontrib-qthelp          1.0.3
sphinxcontrib-serializinghtml 1.1.5
tomli                         2.0.1
urllib3                       1.26.12
wheel                         0.38.1
$ python ./setup.py build_rst_docs --build-docs --qt-target-path=/usr/include/qt6
...

It takes less than a minute to complete, html are generated but no doc for api.
Does the param --qt-target-path need the source code for qt cpp instead of /usr/include/qt6 here?

friedemannkleint

The option --qt-src-dir to setup.py or the QT_SRC_DIR environment variable should be used to point to the source directory of Qt (as installed by the Maintainenance tool, checked out from the git repository or from a source tarball), specifically to the qtbase directory within the tree. The include directories are not sufficient for this.

As for the requirements, only graphviz should be installed on top of requirements.txt, that is indeed wrong.

jronald

Thanks very much, it saved me.

A little tricky, qt6 source is at https://code.qt.io/cgit/qt/qt5.git/
Ref: https://wiki.qt.io/Building_Qt_6_from_Git

jronald

@friedemannkleint

New error

$ python setup.py build_rst_docs --build-docs --qt-src-dir=/path/to/qtbase
...
RuntimeError: Could not run /usr/bin/qtpaths: None
...

$ whereis qtpaths
qtpaths: /usr/bin/qtpaths

JonB

@jronald
Just make sure what file /usr/bin/qtpaths and ls -l /usr/bin/qtpaths return? And try running it yourself from a terminal.

jronald

UPDATE

$ python setup.py build_rst_docs --build-docs --qt-src-dir=/path/to/qt6/qtbase
...
qtpaths: Unknown option 'qt-query'.

Could not find Qt. You can pass the --qt-target-path=<qt-dir> option as a hint where to find Qt. Error was:

@JonB said in Failed to build doc for pyside6 in qch by following the doc:

Just make sure what file /usr/bin/qtpaths and ls -l /usr/bin/qtpaths return? And try running it yourself from a terminal.

$ file /usr/bin/qtpaths
/usr/bin/qtpaths: ELF 64-bit LSB pie executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, BuildID[sha1]=77022ee7473a4933ba05ccf4d55e33d4ee4143b0, for GNU/Linux 4.4.0, stripped
$ ls -l /usr/bin/qtpaths
-rwxr-xr-x 1 root root 30808 Sep  8 16:51 /usr/bin/qtpaths
$ /usr/bin/qtpaths --qt-version
5.15.6

When both Qt5 and Qt6 are installed, it finds 5.15.6 instead of 6.4.0.
Is this a problem?

jronald

New problem

$ python setup.py build_rst_docs --build-docs --qt-target-path=/usr --qt-src-dir=/path/to/qtbase
...
running build_rst_docs
-- This build process will not include the API documentation.API documentation requires a full build of pyside/shiboken.
...

Does it have to build the pyside6 first and then use the intermediate stuff for building to genereate the doc for pyside6?

friedemannkleint

If you want the full API docs, you need to build PySide 6 yourself, as described in the getting started page. You also need to get rid of Qt 5. If Qt 6 is installed by the Online installer, make sure it is first in PATH. If it comes from the system, find the Qt6 qtpaths binary and pass that using the --qtpaths option of setup.py.
The --qt-target-path= option is for cross builds only; it should not be used here.

jronald

@friedemannkleint said in Failed to build doc for pyside6 in qch by following the doc:

If you want the full API docs, you need to build PySide 6 yourself, as described in the getting started page.

I've built it in pyside-setup/out/, how to use it?

$ python setup.py build_rst_docs --build-docs --qtpaths=/usr/lib/qt6/bin/qtpaths --qt=6 --qt-src-dir=/path/to/qt6/qtbase
...
This build process will not include the API documentation.API documentation requires a full build of pyside/shiboken.
...

friedemannkleint

Have you checked https://doc.qt.io/qtforpython-6/gettingstarted.html ? Do you have libxml, libxslt (dev packages) and graphviz installed? You then need to go to the build directory (something like build/testenv_td/build/pyside6) and then run ninja apidoc as described.

jronald

@friedemannkleint said in Failed to build doc for pyside6 in qch by following the doc:

Have you checked https://doc.qt.io/qtforpython-6/gettingstarted.html ?

Yes, I've read it several times.

Do you have libxml, libxslt (dev packages) and graphviz installed?

Yes

You then need to go to the build directory (something like build/testenv_td/build/pyside6) and then run ninja apidoc as described.

I can't find the directory.

UPDATE

Now using python setup.py install ... instead of cmake to build, it seems ok, in progress.

$ python setup.py install --build-docs --qtpaths=/usr/lib/qt6/bin/qtpaths --qt-src-dir=/path/to/qt6/qtbase --ignore-git --parallel=8

jronald

New error

$ ninja apidoc
...
qtpaths: Unknown options: q, u, e, r, y.
Traceback (most recent call last):
  File "/path/to/pyside-setup/sources/pyside6/doc/qtattributionsscannertorst.py", line 102, in <module>
    runScanner(directory, targetFileName)
  File "/path/to/pyside-setup/sources/pyside6/doc/qtattributionsscannertorst.py", line 67, in runScanner
    libexec_b = subprocess.check_output('qtpaths -query QT_INSTALL_LIBEXECS',
  File "/usr/lib/python3.10/subprocess.py", line 421, in check_output
    return run(*popenargs, stdout=PIPE, timeout=timeout, check=True,
  File "/usr/lib/python3.10/subprocess.py", line 526, in run
    raise CalledProcessError(retcode, process.args,
subprocess.CalledProcessError: Command 'qtpaths -query QT_INSTALL_LIBEXECS' returned non-zero exit status 1.
ninja: build stopped: subcommand failed.

JonB

@jronald said in Failed to build doc for pyside6 in qch by following the doc:

qtpaths: Unknown options: q, u, e, r, y.

Command 'qtpaths -query QT_INSTALL_LIBEXECS' returned non-zero exit status 1.

I know nothing about why this happening/what you are supposed to do about it, but that sounds like something is invoking qtpaths -query when it only accepts qtpaths --query? Try both of these from the command line to see if that is the cause of the error message?

jronald

@JonB said in Failed to build doc for pyside6 in qch by following the doc:

I know nothing about why this happening/what you are supposed to do about it, but that sounds like something is invoking qtpaths -query when it only accepts qtpaths --query? Try both of these from the command line to see if that is the cause of the error message?

$ /usr/lib/qt6/bin/qtpaths --query QT_INSTALL_LIBEXECS
/usr/lib/qt6

It's a bug in /path/to/pyside-setup/sources/pyside6/doc/qtattributionsscannertorst.py:

libexec_b = subprocess.check_output('qtpaths -query QT_INSTALL_LIBEXECS',
                                    shell=True)

The codes below also don't work, because qtpaths here is for qt5 and it doesn't support --query,
qtpaths here should be controlled by the command param --qtpaths

libexec_b = subprocess.check_output('qtpaths --query QT_INSTALL_LIBEXECS',
                                    shell=True)

The codes below work as a temp solution.

libexec_b = subprocess.check_output('/usr/lib/qt6/bin/qtpaths --query QT_INSTALL_LIBEXECS',
                                    shell=True)

jronald

screenshot

jronald

Summary

pyside-setup-path=...
venv-name=...
venv-prefix=...
venv-path=${venv-prefix}/${venv-name}
qtpaths-exe-path=... # e.g. /usr/lib/qt6/bin/qtpaths
qt-src-path=... # qtbase path in source tree, e.g. /path/to/qt6-src/qtbase

python -m venv ${venv-path}
source ${venv-path}/bin/activate

cd ${venv-path}

pip install -r requirements.txt
pip install graphviz

# build pyside6 doc
cd ${pyside-setup-path}
python ./setup.py build_rst_docs

# build api doc
python setup.py install --build-docs --qtpaths=${qtpaths_exe_path} --qt-src-dir=${qt-src-path} --ignore-git --parallel=8

cd ${pyside-setup-path}/build/${venv-name}/build/pyside6
ninja apidoc
# Result: ${pyside-setup-path}/build/${venv-name}/build/pyside6/doc/html/PySide.qch

Bug fix (manjaro)

file

/path/to/pyside-setup/sources/pyside6/doc/qtattributionsscannertorst.py

buggy codes

libexec_b = subprocess.check_output('qtpaths -query QT_INSTALL_LIBEXECS',
                                    shell=True)

fix

libexec_b = subprocess.check_output('/usr/lib/qt6/bin/qtpaths --query QT_INSTALL_LIBEXECS',
                                    shell=True)

friedemannkleint

The qtattributionsscannertorst.py error will be fixed by https://codereview.qt-project.org/c/pyside/pyside-setup/+/442370 , hopefully. As for missing links, did you really pass a Qt source tree - --qt-src-dir=/path/to/qt6/qtbase does not look like it. We use qdoc which needs the source tree.

jronald

@friedemannkleint said in Failed to build doc for pyside6 in qch by following the doc:

As for missing links, did you really pass a Qt source tree - --qt-src-dir=/path/to/qt6/qtbase does not look like it.

Yes, in practice I'm using a real path to qt6/qtbase instead of /path/to/qt6/qtbase as a placeholder here.