vine 5.1.0: documentation not ready for sphinx 6.x

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!

Mar 20 '23 09:03 kloczek

Looks like 5.1.0 still fails.

Nov 05 '23 09:11 kloczek

it is not fixed yet. need a new release of the doc extension https://github.com/celery/sphinx_celery/issues/27

Nov 05 '23 10:11 auvipy

The fail comes from: https://github.com/celery/vine/blob/8c08b391a9f8976153a3a1972c66296e01f60c66/Changelog#L127 sphinx.ext.autosectionlabel extension is needed in docs/conf.py. Please see here

Kind Regards

Nov 05 '23 10:11 s3v-

sphinx.ext.autosectionlabel is part of the standard sphinx and it has nothing to do with case. Other thing is that as wrote in https://github.com/celery/vine/issues/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

Nov 05 '23 11:11 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'],

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

Nov 05 '23 12:11 s3v-

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

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

Nov 05 '23 14:11 s3v-

Thanks s3v

Nov 05 '23 15:11 auvipy

@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. https://github.com/celery/vine/blob/8c08b391a9f8976153a3a1972c66296e01f60c66/docs/conf.py#L19

Nov 05 '23 15:11 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. https://github.com/RDFLib/rdflib-sqlalchemy/issues/95 https://github.com/RDFLib/rdflib/pull/2036 https://github.com/click-contrib/sphinx-click/commit/abc31069 https://github.com/frostming/unearth/issues/14 https://github.com/jaraco/cssutils/issues/21 https://github.com/latchset/jwcrypto/pull/289 https://github.com/latchset/jwcrypto/pull/289 https://github.com/pypa/distlib/commit/98b9b89f https://github.com/pywbem/pywbem/pull/2895 https://github.com/sissaschool/elementpath/commit/bf869d9e https://github.com/sissaschool/xmlschema/commit/42ea98f2 https://github.com/sqlalchemy/sqlalchemy/commit/5e88e6e8

Apr 06 '24 16:04 kloczek