document the required version of sphinx

[twisted-trac]

	@exarkun reported
Trac ID	trac#6903
Type	defect
Created	2014-01-16 11:14:29Z

The version of sphinx I have generates an empty skeleton containing no actual documentation. The version of sphinx buildbot has apparently does the same.

Searchable metadata

trac-id__6903 6903
type__defect defect
reporter__exarkun exarkun
priority__normal normal
milestone__ 
branch__ 
branch_author__ 
status__closed closed
resolution__fixed fixed
component__core core
keywords__documentation documentation
time__1389870869000000 1389870869000000
changetime__1612647124023272 1612647124023272
version__None None
owner__adiroiban adiroiban

[twisted-trac]

	@dstufft commented

There's a config parameter for Sphinx that will have it bomb out with a useful error message if your sphinx isn't at least that FWIW. I believe that is how it works anyways.

[twisted-trac]

	@exarkun commented

See also https://bugs.launchpad.net/twisted-buildbot-configuration/+bug/1269764

[twisted-trac]

	@khorn commented

The relevant Sphinx parameter is "needs_sphinx":
http://sphinx-doc.org/config.html#confval-needs_sphinx

exarkun, is this still an issue? The config value above seems to be present in the conf.py file. Can we close this?

(and maybe also the related buildbot config ticket?)

[twisted-trac]

	@exarkun commented

I svn blamed the conf.py and found the needs_sphinx was introduced in r42144. This revision resolved #6926. It seems the exact same issue was noticed when working on that ticket and resolved there.

I don't know about buildbot configuration. Perhaps Tom or Glyph does.

[twisted-trac]

	@adiroiban removed owner

in conf.py we have

# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = "1.2"

In setup.cfg we have

dev_release =
    towncrier >= 17.4.0
    pydoctor >= 20.12.1; python_version >= "3.6"
    sphinx-rtd-theme~=0.5.0
    readthedocs-sphinx-ext~=2.1
    sphinx~=3.3

I think that just defining the version in setup.cfg is enough ... and we don't need to also update conf.py.

Putting more work into fixing this looks like effort that will not get us much further than we are now.

I will send a PR to remove the needs_python from conf.py to reduce the confusion.

[twisted-trac]

	@adiroiban commented

PR at #1508

[twisted-trac]

	@exarkun set owner to @adiroiban

[twisted-trac]

	@adiroiban set status to closed

In changeset 8c132d2

#!CommitTicketReference repository="" revision="8c132d24e08d75c1cd33946d4c996edb8f560f20"
Merge pull request #1508 from twisted/6903-sphinx-req-version

Author: adiroiban
Reviewer: exarkun
Fixes: ticket:6903

Configure the required Sphinx version only in setup.cfg.