search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.56k stars 2.12k forks source link

Multiple builders setting in setuptools returns a warning (Sphinx 1.6.5) #4259

Closed ianychoi closed 6 years ago

ianychoi commented 6 years ago

Problem

Of course, "warning-is-error = 0" in setup.cfg makes it work fine, but since the warning is not from actual documentation, it would not be treated as warnings I think. Just either "builder = html" or "builder = latex" works without any warnings.

Procedure to reproduce the problem

$ git clone git://git.openstack.org/openstack/horizon
$ cd horizon
(Adds "builder = html,latex" in setup.cfg - [build_sphinx] section)
$ rm -rf .tox/venv
(Not required unless you did not execute the next command previously)
$ tox -evenv -- python setup.py build_sphinx

Error logs / results

The warning message is:

Warning, treated as error:
while setting up extension ['?', 'sphinx.ext.todo']: node class 'todolist' is already registered, its visitors will be overridden

, and the full log is:

$ tox -e venv -- python setup.py build_sphinx
venv installed: alabaster==0.7.10,appdirs==1.4.3,asn1crypto==0.23.0,Babel==2.5.1,certifi==2017.11.5,cffi==1.11.2,chardet==3.0.4,cliff==2.9.1,cmd2==0.7.8,colorama==0.3.9,contextlib2==0.5.5,coverage==4.4.2,cryptography==2.1.3,debtcollector==1.18.0,Django==1.11.7,django-appconf==1.0.2,django-babel==0.6.1,django-compressor==2.2,django-nose==1.4.5,django-pyscss==2.0.2,doc8==0.8.0,docutils==0.14,dulwich==0.18.6,enum34==1.1.6,extras==1.0.0,fasteners==0.14.1,fixtures==3.0.0,flake8==2.5.5,flake8-import-order==0.12,funcsigs==1.0.2,functools32==3.2.3.post2,futures==3.1.1,futurist==1.4.0,hacking==0.12.0,horizon==13.0.0.0b2.dev90,idna==2.6,imagesize==0.7.1,ipaddress==1.0.18,iso8601==0.1.11,Jinja2==2.10,jsonpatch==1.16,jsonpointer==1.14,jsonschema==2.6.0,keystoneauth1==3.2.0,linecache2==1.0.0,MarkupSafe==1.0,mccabe==0.2.1,mock==2.0.0,monotonic==1.4,mox3==0.23.0,msgpack-python==0.4.8,netaddr==0.7.19,netifaces==0.10.6,nodeenv==1.2.0,nose==1.3.7,nose-exclude==0.5.0,nosehtmloutput==0.0.5,nosexcover==1.0.11,openstack.nose-plugin==0.11,openstackdocstheme==1.17.0,os-client-config==1.28.0,osc-lib==1.7.0,oslo.concurrency==3.23.0,oslo.config==5.1.0,oslo.i18n==3.18.0,oslo.policy==1.30.0,oslo.serialization==2.21.1,oslo.utils==3.31.0,osprofiler==1.14.0,pathlib==1.0.1,pbr==3.1.1,pep8==1.5.7,Pint==0.8.1,positional==1.2.1,prettytable==0.7.2,pycodestyle==2.3.1,pycparser==2.18,pyflakes==0.8.1,Pygments==2.2.0,pymongo==3.5.1,pyOpenSSL==17.3.0,pyparsing==2.2.0,pyperclip==1.6.0,pyScss==1.3.4,python-cinderclient==3.2.0,python-glanceclient==2.8.0,python-heatclient==1.12.0,python-keystoneclient==3.13.0,python-mimeparse==1.6.0,python-neutronclient==6.5.0,python-novaclient==9.1.1,python-swiftclient==3.4.0,pytz==2017.3,PyYAML==3.12,rcssmin==1.0.6,reno==2.6.0,requests==2.18.4,requestsexceptions==1.3.0,restructuredtext-lint==1.1.2,rfc3986==1.1.0,rjsmin==1.0.12,selenium==3.7.0,semantic-version==2.6.0,simplejson==3.12.0,six==1.11.0,snowballstemmer==1.2.1,Sphinx==1.6.5,sphinxcontrib-websupport==1.0.1,stevedore==1.27.1,termcolor==1.1.0,testscenarios==0.5.0,testtools==2.3.0,traceback2==1.4.0,typing==3.6.2,unicodecsv==0.14.1,unittest2==1.1.0,urllib3==1.22,warlock==1.2.0,WebOb==1.7.3,wrapt==1.10.11,XStatic==1.0.1,XStatic-Angular==1.5.8.0,XStatic-Angular-Bootstrap==2.2.0.0,XStatic-Angular-FileUpload==12.0.4.0,XStatic-Angular-Gettext==2.3.8.0,XStatic-Angular-lrdragndrop==1.0.2.2,XStatic-Angular-Schema-Form==0.8.13.0,XStatic-Bootstrap-Datepicker==1.3.1.0,XStatic-Bootstrap-SCSS==3.3.7.1,XStatic-bootswatch==3.3.7.0,XStatic-D3==3.5.17.0,XStatic-Font-Awesome==4.7.0.0,XStatic-Hogan==2.0.0.2,XStatic-Jasmine==2.4.1.1,XStatic-jQuery==1.10.2.1,XStatic-JQuery-Migrate==1.2.1.1,XStatic-jquery-ui==1.12.0.1,XStatic-JQuery.quicksearch==2.0.3.1,XStatic-JQuery.TableSorter==2.14.5.1,XStatic-JSEncrypt==2.3.1.1,XStatic-mdi==1.4.57.0,XStatic-objectpath==1.2.1.0,XStatic-Rickshaw==1.5.0.0,XStatic-roboto-fontface==0.5.0.0,XStatic-smart-table==1.4.13.2,XStatic-Spin==1.2.5.2,XStatic-term.js==0.0.7.0,XStatic-tv4==1.2.7.0,xvfbwrapper==0.2.9
venv runtests: PYTHONHASHSEED='405249795'
venv runtests: commands[0] | python setup.py build_sphinx
running build_sphinx
[pbr] Writing ChangeLog
[pbr] Generating ChangeLog
[pbr] ChangeLog complete (0.3s)
[pbr] Generating AUTHORS
[pbr] AUTHORS complete (0.5s)
Running Sphinx v1.6.5
connecting events for openstackdocstheme
loading pickled environment... done
Using openstackdocstheme Sphinx theme from /home/ian/git/openstack/horizon/.tox/venv/local/lib/python2.7/site-packages/openstackdocstheme/theme
building [mo]: all of 0 po files
building [html]: all source files
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
preparing documents... done
writing output... [  1%] admin/admin-manage-roles
writing output... [  2%] admin/customize-configure
writing output... [  3%] admin/index
writing output... [  4%] admin/manage-flavors
writing output... [  5%] admin/manage-host-aggregates
writing output... [  7%] admin/manage-images
writing output... [  8%] admin/manage-instances
writing output... [  9%] admin/manage-projects-and-users
writing output... [ 10%] admin/manage-services
writing output... [ 11%] admin/manage-shares
writing output... [ 13%] admin/manage-volumes
writing output... [ 14%] admin/sessions
writing output... [ 15%] admin/set-quotas
writing output... [ 16%] configuration/branding
writing output... [ 17%] configuration/customizing
writing output... [ 19%] configuration/index
writing output... [ 20%] configuration/pluggable_panels
writing output... [ 21%] configuration/settings
writing output... [ 22%] configuration/themes
writing output... [ 23%] contributor/contributing
writing output... [ 25%] contributor/faq
writing output... [ 26%] contributor/index
writing output... [ 27%] contributor/intro
writing output... [ 28%] contributor/quickstart
writing output... [ 29%] contributor/ref/backend
writing output... [ 30%] contributor/ref/context_processors
writing output... [ 32%] contributor/ref/decorators
writing output... [ 33%] contributor/ref/exceptions
writing output... [ 34%] contributor/ref/forms
writing output... [ 35%] contributor/ref/horizon
writing output... [ 36%] contributor/ref/index
writing output... [ 38%] contributor/ref/local_conf
writing output... [ 39%] contributor/ref/middleware
writing output... [ 40%] contributor/ref/tables
writing output... [ 41%] contributor/ref/tabs
writing output... [ 42%] contributor/ref/test
writing output... [ 44%] contributor/ref/user
writing output... [ 45%] contributor/ref/utils
writing output... [ 46%] contributor/ref/views
writing output... [ 47%] contributor/ref/workflows
writing output... [ 48%] contributor/testing
writing output... [ 50%] contributor/topics/angularjs
writing output... [ 51%] contributor/topics/index
writing output... [ 52%] contributor/topics/javascript_testing
writing output... [ 53%] contributor/topics/microversion_support
writing output... [ 54%] contributor/topics/packaging
writing output... [ 55%] contributor/topics/policy
writing output... [ 57%] contributor/topics/styling
writing output... [ 58%] contributor/topics/tables
writing output... [ 59%] contributor/topics/testing
writing output... [ 60%] contributor/topics/translation
writing output... [ 61%] contributor/topics/workflows
writing output... [ 63%] contributor/tutorials/dashboard
writing output... [ 64%] contributor/tutorials/index
writing output... [ 65%] contributor/tutorials/plugin
writing output... [ 66%] contributor/tutorials/table_actions
writing output... [ 67%] contributor/tutorials/workflow_extend
writing output... [ 69%] glossary
writing output... [ 70%] index
writing output... [ 71%] install/from-source
writing output... [ 72%] install/index
writing output... [ 73%] install/install-debian
writing output... [ 75%] install/install-obs
writing output... [ 76%] install/install-rdo
writing output... [ 77%] install/install-ubuntu
writing output... [ 78%] install/next-steps
writing output... [ 79%] install/plugin-registry
writing output... [ 80%] install/verify-debian
writing output... [ 82%] install/verify-obs
writing output... [ 83%] install/verify-rdo
writing output... [ 84%] install/verify-ubuntu
writing output... [ 85%] user/browser_support
writing output... [ 86%] user/configure-access-and-security-for-instances
writing output... [ 88%] user/create-networks
writing output... [ 89%] user/databases
writing output... [ 90%] user/index
writing output... [ 91%] user/launch-instances
writing output... [ 92%] user/log-in
writing output... [ 94%] user/manage-containers
writing output... [ 95%] user/manage-images
writing output... [ 96%] user/manage-lbaasv2
writing output... [ 97%] user/manage-shares
writing output... [ 98%] user/manage-volumes
writing output... [100%] user/stacks

generating indices... genindex py-modindex
highlighting module code... [  3%] horizon.tables.base
highlighting module code... [  7%] horizon.tabs.views
highlighting module code... [ 11%] horizon.tables.formset
highlighting module code... [ 15%] openstack_auth.views
highlighting module code... [ 19%] horizon.base
highlighting module code... [ 23%] horizon.exceptions
highlighting module code... [ 26%] openstack_auth.forms
highlighting module code... [ 30%] django.utils.functional
highlighting module code... [ 34%] horizon.tabs.base
highlighting module code... [ 38%] horizon.workflows.base
highlighting module code... [ 42%] horizon.tables.views
highlighting module code... [ 46%] horizon.tables.actions
highlighting module code... [ 50%] horizon.forms.fields
highlighting module code... [ 53%] horizon.forms.base
highlighting module code... [ 57%] horizon.middleware.operation_log
highlighting module code... [ 61%] horizon.decorators
highlighting module code... [ 65%] horizon.forms.views
highlighting module code... [ 69%] openstack_auth.backend
highlighting module code... [ 73%] horizon.context_processors
highlighting module code... [ 76%] openstack_auth.user
highlighting module code... [ 80%] django.utils.safestring
highlighting module code... [ 84%] horizon.workflows.views
highlighting module code... [ 88%] openstack_dashboard.test.helpers
highlighting module code... [ 92%] horizon.middleware.base
highlighting module code... [ 96%] openstack_auth.utils
highlighting module code... [100%] horizon.test.helpers

writing additional pages... search
copying images... [  9%] contributor/topics/../../images/message_substitution.png
copying images... [ 18%] user/figures/dashboard_settings_tab.png
copying images... [ 27%] user/figures/dashboard_admin_tab.png
copying images... [ 36%] user/figures/dashboard_identity_tab.png
copying images... [ 45%] user/figures/dashboard_project_tab.png
copying images... [ 54%] contributor/topics/../../images/message_extraction.png
copying images... [ 63%] admin/figures/create_flavor.png
copying images... [ 72%] admin/figures/change_instance_state.png
copying images... [ 81%] user/figures/create_image.png
copying images... [ 90%] admin/figures/create_volume_type_encryption.png
copying images... [100%] admin/figures/create_image.png

copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.
Running Sphinx v1.6.5

Warning, treated as error:
while setting up extension ['?', 'sphinx.ext.todo']: node class 'todolist' is already registered, its visitors will be overridden
ERROR: InvocationError: '/home/ian/git/openstack/horizon/.tox/venv/bin/python setup.py build_sphinx'
___________________________________ summary ____________________________________
ERROR:   venv: commands failed

Expected results

Successfully executed without any warning and outputs will be in both doc/build/html and doc/build/latex folders.

Reproducible project / your project

Environment info

tk0miya commented 6 years ago

Could you let me know what the warnings are emitted without -W option? I will fix the warning for node classes later. But I'd like to know what the warnings are emitted any other.

stephenfin commented 6 years ago

I can take this, seeing as I broke it. It's an issue with docutils' use of global state - we should either make sphinx.application.Application a singleton or, better, store that global state as part of the sphinx.application.Application or sphinx.registry.Registry objects.

tk0miya commented 6 years ago

Yes, that is purpose of the registry class. Now I'm going to move components step by step. The nodes are next target of my refactoring.

tk0miya commented 6 years ago

Note: docutils is designed to store components in global. So essentially it is hard to change not to store all status in global. But I try to keep the effects to limited scopes with "write back" techniques. For example, sphinx.util.docutils:sphinx_domain() goes to restore the registered directive and roles after processing. https://github.com/sphinx-doc/sphinx/blob/3413590edd75af664f46b2fcd5e50c18c4c4ec79/sphinx/util/docutils.py#L85-L157

tk0miya commented 6 years ago

It seems current master branch does not emit any warnings for horizon docs. So I'm closing this. Please let me know if you still have other issue.

Thanks,