5.1.0: documentation not ready for sphinx 6.x

[kloczek]

Looks lie vine documentation is not ready to be generated using sphinx 6.x

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v6.1.3
making output directory... done
loading intersphinx inventory from https://docs.python.org/dev/objects.inv...
loading intersphinx inventory from https://www.sphinx-doc.org/en/stable/objects.inv...
intersphinx inventory has moved: https://www.sphinx-doc.org/en/stable/objects.inv -> https://www.sphinx-doc.org/en/master/objects.inv
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 8 added, 0 changed, 0 removed
reading sources... [ 12%] changelog

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 284, in build_main
    app.build(args.force_all, args.filenames)
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 347, in build
    self.builder.build_update()
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 308, in build_update
    self.build(['__all__'], to_build)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 327, in build
    updated_docnames = set(self.read())
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 434, in read
    self._read_serial(docnames)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 455, in _read_serial
    self.read_doc(docname)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 511, in read_doc
    publisher.publish()
  File "/usr/lib/python3.8/site-packages/docutils/core.py", line 224, in publish
    self.document = self.reader.read(self.source, self.parser,
  File "/usr/lib/python3.8/site-packages/sphinx/io.py", line 105, in read
    self.parse()
  File "/usr/lib/python3.8/site-packages/docutils/readers/__init__.py", line 76, in parse
    self.parser.parse(self.input, document)
  File "/usr/lib/python3.8/site-packages/sphinx/parsers.py", line 80, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 169, in run
    results = StateMachineWS.run(self, input_lines, input_offset,
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2785, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 325, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 391, in new_subsection
    newabsoffset = self.nested_parse(
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 279, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 1273, in bullet
    i, blank_finish = self.list_item(match.end())
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 1295, in list_item
    self.nested_parse(indented, input_offset=line_offset,
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 279, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2716, in blank
    paragraph, literalnext = self.paragraph(
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 416, in paragraph
    textnodes, messages = self.inline_text(text, lineno)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 425, in inline_text
    nodes, messages = self.inliner.parse(text, lineno,
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 649, in parse
    before, inlines, remaining, sysmessages = method(self, match,
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 792, in interpreted_or_phrase_ref
    nodelist, messages = self.interpreted(rawsource, escaped, role,
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 889, in interpreted
    nodes, messages2 = role_fn(role, rawsource, text, lineno, self)
  File "/usr/lib/python3.8/site-packages/sphinx/ext/extlinks.py", line 103, in role
    title = caption % part
TypeError: not all arguments converted during string formatting

Exception occurred:
  File "/usr/lib/python3.8/site-packages/sphinx/ext/extlinks.py", line 103, in role
    title = caption % part
TypeError: not all arguments converted during string formatting
The full traceback has been saved in /tmp/sphinx-err-7nuo7zx_.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

[kloczek]

Looks like 5.1.0 still fails.

[auvipy]

it is not fixed yet. need a new release of the doc extension celery/sphinx_celery#27

[s3v-]

The fail comes from:

vine/Changelog

Line 127 in 8c08b39

- Requirements: Tests now depends on :pypi:`case` 1.2.2

sphinx.ext.autosectionlabel extension is needed in docs/conf.py.
Please see here

Kind Regards

[kloczek]

sphinx.ext.autosectionlabel is part of the standard sphinx and it has nothing to do with case.
Other thing is that as wrote in #61 thicket case is no longer maintained since 2017.

Second thing is that in https://github.com/celery/vine/blob/master/docs/conf.py there is no listed any extensions = [].
Please have look on https://www.sphinx-doc.org/en/master/usage/configuration.html#example-of-configuration-file

[s3v-]

@kloczek

I don't fully understand your comment.
This issue comes from that line in vine/changelog and not from case itself.
Adding:

extensions = ['sphinx.ext.autosectionlabel'],

in conf.py makes docs buildable in html although generated html is pretty ugly:

<li><p>Requirements: Tests now depends on <a href="#id8"><span class="problematic" id="id9">:pypi:`case`</span></a> 1.2.2</p></li>

Maybe hardcoding external URL in changelog is a good idea?

Kind Regards

[s3v-]

Hi again,
as @auvipy said, sphinx-celery needs to be compatible with new Sphinx.
This commit solves the issue:
celery/sphinx_celery@e2f88da
Notably:

     ))
     extlinks.setdefault('pypi', (
-        'https://pypi.org/project/%s/', '',
+        'https://pypi.org/project/%s/', None,
     ))

[auvipy]

Thanks s3v

[kloczek]

@kloczek

I don't fully understand your comment. This issue comes from that line in vine/changelog and not from case itself. Adding:

extensions = ['sphinx.ext.autosectionlabel'],

Currently list of used extensions is empty.

vine/docs/conf.py

Line 19 in 8c08b39

extra_extensions=[],

[kloczek]

Just retested with Sphinx 7.2.6 and look like +/- nitpick warnings it is possible to generate documentation

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v7.2.6
making output directory... done
loading intersphinx inventory from https://docs.python.org/dev/objects.inv...
loading intersphinx inventory from https://www.sphinx-doc.org/en/stable/objects.inv...
intersphinx inventory has moved: https://www.sphinx-doc.org/en/stable/objects.inv -> https://www.sphinx-doc.org/en/master/objects.inv
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 8 added, 0 changed, 0 removed
reading sources... [100%] reference/vine.utils
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-vine.3 { reference/index reference/vine.promises reference/vine.synchronization reference/vine.funtools reference/vine.abstract reference/vine.utils changelog } /home/tkloczko/rpmbuild/BUILD/vine-5.1.0/Changelog:47: WARNING: py:mod reference target not found: vine.five
/home/tkloczko/rpmbuild/BUILD/vine-5.1.0/Changelog:51: WARNING: py:mod reference target not found: vine.backports.weakref_backports
/home/tkloczko/rpmbuild/BUILD/vine-5.1.0/Changelog:147: WARNING: py:class reference target not found: vine.abstract.ThenableProxy
/home/tkloczko/rpmbuild/BUILD/vine-5.1.0/Changelog:175: WARNING: py:const reference target not found: None
done
build succeeded, 4 warnings.

Here is batch of examples from other projects about how to fix reference target not found warnings.
RDFLib/rdflib-sqlalchemy#95
RDFLib/rdflib#2036
click-contrib/sphinx-click@abc31069
frostming/unearth#14
jaraco/cssutils#21
latchset/jwcrypto#289
latchset/jwcrypto#289
pypa/distlib@98b9b89f
pywbem/pywbem#2895
sissaschool/elementpath@bf869d9e
sissaschool/xmlschema@42ea98f2
sqlalchemy/sqlalchemy@5e88e6e8