search

qiskit-community / qiskit-dynamics

Tools for building and solving models of quantum systems in Qiskit
https://qiskit-community.github.io/qiskit-dynamics/
Apache License 2.0
105 stars 61 forks source link

Trouble building documentation locally #138

Closed ihincks closed 2 years ago

ihincks commented 2 years ago

Informations

What is the current behavior?

autosummary is getting confused about the contents of array.Array and failing the build. Previous debugging of this sort of stuff leads me to believe it's only complaining about array because it comes first alphabetically.

Steps to reproduce the problem

Setup:

mkdir tmp && cd tmp
python -m venv .venv
source .venv/bin/activate

git clone git@github.com:Qiskit/qiskit-dynamics.git --depth 1
cd qiskit-dynamics && git rev-parse HEAD
>>> e8a2eb883a9c03385b2cfa98993f051d4d24c829

pip install -r requirements-dev.txt
pip install -e .
pip freeze

alabaster==0.7.12
appnope==0.1.3
astroid==2.9.3
asttokens==2.0.8
attrs==22.1.0
autopage==0.5.1
Babel==2.10.3
backcall==0.2.0
beautifulsoup4==4.11.1
black==22.10.0
bleach==5.0.1
certifi==2022.9.24
charset-normalizer==2.1.1
click==8.1.3
cliff==4.0.0
cmd2==2.4.2
contourpy==1.0.5
cycler==0.11.0
ddt==1.4.4
debugpy==1.6.3
decorator==5.1.1
defusedxml==0.7.1
dill==0.3.5.1
docutils==0.19
dulwich==0.20.46
entrypoints==0.4
executing==1.1.1
extras==1.0.0
fastjsonschema==2.16.2
fixtures==4.0.1
fonttools==4.37.4
future==0.18.2
idna==3.4
imagesize==1.4.1
importlib-metadata==5.0.0
ipykernel==6.16.1
ipython==8.5.0
ipywidgets==8.0.2
isort==5.10.1
jedi==0.18.1
Jinja2==3.1.2
jsonschema==4.16.0
jupyter-sphinx==0.4.0
jupyter_client==7.4.3
jupyter_core==4.11.2
jupyterlab-pygments==0.2.2
jupyterlab-widgets==3.0.3
kiwisolver==1.4.4
latexcodec==2.0.1
lazy-object-proxy==1.7.1
MarkupSafe==2.1.1
matplotlib==3.6.1
matplotlib-inline==0.1.6
mccabe==0.6.1
mistune==2.0.4
mpmath==1.2.1
multiset==3.0.1
mypy-extensions==0.4.3
nbclient==0.7.0
nbconvert==7.2.2
nbformat==5.7.0
nbsphinx==0.8.9
nest-asyncio==1.5.6
numpy==1.23.4
packaging==21.3
pandocfilters==1.5.0
parso==0.8.3
pathspec==0.10.1
pbr==5.11.0
pexpect==4.8.0
pickleshare==0.7.5
Pillow==9.2.0
platformdirs==2.5.2
ply==3.11
prettytable==3.4.1
prompt-toolkit==3.0.31
psutil==5.9.3
ptyprocess==0.7.0
pure-eval==0.2.2
pybtex==0.24.0
pybtex-docutils==1.0.2
Pygments==2.13.0
pylint==2.12.2
pyparsing==3.0.9
pyperclip==1.8.2
pyrsistent==0.18.1
python-dateutil==2.8.2
python-subunit==1.4.0
pytz==2022.5
PyYAML==6.0
pyzmq==24.0.1
-e git+ssh://git@github.com/Qiskit/qiskit-dynamics.git@e8a2eb883a9c03385b2cfa98993f051d4d24c829#egg=qiskit_dynamics
qiskit-sphinx-theme==1.9.0
qiskit-terra==0.22.0
qutip==4.7.0
reno==3.5.0
requests==2.28.1
retworkx==0.12.0
rustworkx==0.12.0
scipy==1.9.3
six==1.16.0
snowballstemmer==2.2.0
soupsieve==2.3.2.post1
Sphinx==5.3.0
sphinx_autodoc_typehints==1.19.4
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-bibtex==2.5.0
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
stack-data==0.5.1
stestr==4.0.1
stevedore==4.1.0
symengine==0.9.2
sympy==1.11.1
testtools==2.5.0
tinycss2==1.2.1
toml==0.10.2
tomli==2.0.1
tornado==6.2
traitlets==5.5.0
typing_extensions==4.4.0
urllib3==1.26.12
voluptuous==0.13.1
wcwidth==0.2.5
webencodings==0.5.1
widgetsnbextension==4.0.3
wrapt==1.13.3
zipp==3.9.0

Build attempt:

python -m sphinx -b html -W docs/ docs/_build/html

Returns:

Running Sphinx v5.3.0
making output directory... done
checking bibtex cache... out of date
parsing bibtex file /Users/ihincks/ttmp/qiskit-dynamics/docs/refs.bib... parsed 12 entries
[autosummary] generating autosummary for: apidocs/array.rst, apidocs/dispatch.rst, apidocs/index.rst, apidocs/models.rst, apidocs/perturbation.rst, apidocs/pulse.rst, apidocs/signals.rst, apidocs/solvers.rst, discussions/dyson_magnus.rst, discussions/index.rst, ..., release_notes.rst, tutorials/Lindblad_dynamics_simulation.rst, tutorials/Rabi_oscillations.rst, tutorials/index.rst, tutorials/optimizing_pulse_sequence.rst, tutorials/qiskit_pulse.rst, userguide/how_to_configure_simulations.rst, userguide/how_to_use_jax.rst, userguide/index.rst, userguide/perturbative_solvers.rst
[autosummary] generating autosummary for: /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.array.Array.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.array.wrap.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.dispatch.asarray.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.dispatch.requires_backend.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.models.GeneratorModel.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.models.HamiltonianModel.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.models.LindbladModel.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.models.RotatingFrame.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.models.rotating_wave_approximation.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.perturbation.ArrayPolynomial.rst, ..., /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.signals.DiscreteSignalSum.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.signals.IQMixer.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.signals.Signal.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.signals.SignalList.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.signals.SignalSum.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.solvers.DysonSolver.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.solvers.MagnusSolver.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.solvers.Solver.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.solvers.solve_lmde.rst, /Users/ihincks/ttmp/qiskit-dynamics/docs/stubs/qiskit_dynamics.solvers.solve_ode.rst

Warning, treated as error:
[autosummary] failed to import qiskit_dynamics.array.Array.available_backends.
Possible hints:
* ImportError: 
* AttributeError: module 'qiskit_dynamics.array.Array' has no attribute 'available_backends'
* ModuleNotFoundError: No module named 'qiskit_dynamics.array.Array.available_backends'; 'qiskit_dynamics.array.Array' is not a package
*

As usual, the -P option on sphinx is useless.

Unsurprisingly, same behaviour with tox as the environment is basically identical:

pip intsall tox
(.venv) ihincks@Ians-MacBook-Pro qiskit-dynamics % which tox
/Users/ihincks/ttmp/.venv/bin/tox
(.venv) ihincks@Ians-MacBook-Pro qiskit-dynamics % tox -edocs
docs create: /Users/ihincks/ttmp/qiskit-dynamics/.tox/docs
docs installdeps: -r/Users/ihincks/ttmp/qiskit-dynamics/requirements-dev.txt, jax, jaxlib, diffrax
docs develop-inst: /Users/ihincks/ttmp/qiskit-dynamics
docs installed: absl-py==1.3.0,alabaster==0.7.12,appnope==0.1.3,astroid==2.9.3,asttokens==2.0.8,attrs==22.1.0,autopage==0.5.1,Babel==2.10.3,backcall==0.2.0,beautifulsoup4==4.11.1,black==22.10.0,bleach==5.0.1,certifi==2022.9.24,charset-normalizer==2.1.1,click==8.1.3,cliff==4.0.0,cmd2==2.4.2,contourpy==1.0.5,cycler==0.11.0,ddt==1.4.4,debugpy==1.6.3,decorator==5.1.1,defusedxml==0.7.1,diffrax==0.2.1,dill==0.3.5.1,docutils==0.19,dulwich==0.20.46,entrypoints==0.4,equinox==0.8.0,etils==0.8.0,executing==1.1.1,extras==1.0.0,fastjsonschema==2.16.2,fixtures==4.0.1,fonttools==4.37.4,future==0.18.2,idna==3.4,imagesize==1.4.1,importlib-metadata==5.0.0,importlib-resources==5.10.0,ipykernel==6.16.1,ipython==8.5.0,ipywidgets==8.0.2,isort==5.10.1,jax==0.3.23,jaxlib==0.3.22,jaxtyping==0.2.7,jedi==0.18.1,Jinja2==3.1.2,jsonschema==4.16.0,jupyter-sphinx==0.4.0,jupyter_client==7.4.3,jupyter_core==4.11.2,jupyterlab-pygments==0.2.2,jupyterlab-widgets==3.0.3,kiwisolver==1.4.4,latexcodec==2.0.1,lazy-object-proxy==1.7.1,MarkupSafe==2.1.1,matplotlib==3.6.1,matplotlib-inline==0.1.6,mccabe==0.6.1,mistune==2.0.4,mpmath==1.2.1,multiset==3.0.1,mypy-extensions==0.4.3,nbclient==0.7.0,nbconvert==7.2.2,nbformat==5.7.0,nbsphinx==0.8.9,nest-asyncio==1.5.6,numpy==1.23.4,opt-einsum==3.3.0,packaging==21.3,pandocfilters==1.5.0,parso==0.8.3,pathspec==0.10.1,pbr==5.11.0,pexpect==4.8.0,pickleshare==0.7.5,Pillow==9.2.0,platformdirs==2.5.2,ply==3.11,prettytable==3.4.1,prompt-toolkit==3.0.31,psutil==5.9.3,ptyprocess==0.7.0,pure-eval==0.2.2,pybtex==0.24.0,pybtex-docutils==1.0.2,Pygments==2.13.0,pylint==2.12.2,pyparsing==3.0.9,pyperclip==1.8.2,pyrsistent==0.18.1,python-dateutil==2.8.2,python-subunit==1.4.0,pytz==2022.5,PyYAML==6.0,pyzmq==24.0.1,-e git+ssh://git@github.com/Qiskit/qiskit-dynamics.git@e8a2eb883a9c03385b2cfa98993f051d4d24c829#egg=qiskit_dynamics,qiskit-sphinx-theme==1.9.0,qiskit-terra==0.22.0,qutip==4.7.0,reno==3.5.0,requests==2.28.1,retworkx==0.12.0,rustworkx==0.12.0,scipy==1.9.3,six==1.16.0,snowballstemmer==2.2.0,soupsieve==2.3.2.post1,Sphinx==5.3.0,sphinx_autodoc_typehints==1.19.4,sphinxcontrib-applehelp==1.0.2,sphinxcontrib-bibtex==2.5.0,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,stack-data==0.5.1,stestr==4.0.1,stevedore==4.1.0,symengine==0.9.2,sympy==1.11.1,testtools==2.5.0,tinycss2==1.2.1,toml==0.10.2,tomli==2.0.1,tornado==6.2,traitlets==5.5.0,typeguard==2.13.3,typing_extensions==4.4.0,urllib3==1.26.12,voluptuous==0.13.1,wcwidth==0.2.5,webencodings==0.5.1,widgetsnbextension==4.0.3,wrapt==1.13.3,zipp==3.9.0
docs run-test-pre: PYTHONHASHSEED='1448775009'
docs run-test: commands[0] | sphinx-build -b html -W docs/ docs/_build/html
Running Sphinx v5.3.0
checking bibtex cache... out of date
parsing bibtex file /Users/ihincks/ttmp/qiskit-dynamics/docs/refs.bib... parsed 12 entries
[autosummary] generating autosummary for: apidocs/array.rst, apidocs/dispatch.rst, apidocs/index.rst, apidocs/models.rst, apidocs/perturbation.rst, apidocs/pulse.rst, apidocs/signals.rst, apidocs/solvers.rst, discussions/dyson_magnus.rst, discussions/index.rst, ..., stubs/qiskit_dynamics.solvers.solve_ode.rst, tutorials/Lindblad_dynamics_simulation.rst, tutorials/Rabi_oscillations.rst, tutorials/index.rst, tutorials/optimizing_pulse_sequence.rst, tutorials/qiskit_pulse.rst, userguide/how_to_configure_simulations.rst, userguide/how_to_use_jax.rst, userguide/index.rst, userguide/perturbative_solvers.rst

Warning, treated as error:
[autosummary] failed to import qiskit_dynamics.array.Array.available_backends.
Possible hints:
* ModuleNotFoundError: No module named 'qiskit_dynamics.array.Array.available_backends'; 'qiskit_dynamics.array.Array' is not a package
* ImportError: 
* AttributeError: module 'qiskit_dynamics.array.Array' has no attribute 'available_backends'
ERROR: InvocationError for command /Users/ihincks/ttmp/qiskit-dynamics/.tox/docs/bin/sphinx-build -b html -W docs/ docs/_build/html (exited with code 2)
_________________________________________________________ summary _________________________________________________________
ERROR:   docs: commands failed

Gives

What is the expected behavior?

Docs should build.

Suggested solutions

ihincks commented 2 years ago

An unsatisfying ending that doesn't answer any questions but does make this problem go away: building with the python that ships with mac os (/usr/bin/python3.9) instead of homebrew python3.9 makes this error disappear.