Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

5.1.0: documentation not ready for sphinx 6.x #82

Open
kloczek opened this issue Mar 20, 2023 · 9 comments
Open

5.1.0: documentation not ready for sphinx 6.x #82

kloczek opened this issue Mar 20, 2023 · 9 comments

Comments

@kloczek
Copy link

kloczek commented Mar 20, 2023

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
Copy link
Author

kloczek commented Nov 5, 2023

Looks like 5.1.0 still fails.

@auvipy
Copy link
Member

auvipy commented Nov 5, 2023

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

@auvipy auvipy changed the title 5.0.0: documentation not ready for sphinx 6.x 5.1.0: documentation not ready for sphinx 6.x Nov 5, 2023
@s3v-
Copy link

s3v- commented Nov 5, 2023

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
Copy link
Author

kloczek commented Nov 5, 2023

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-
Copy link

s3v- commented Nov 5, 2023

@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-
Copy link

s3v- commented Nov 5, 2023

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
Copy link
Member

auvipy commented Nov 5, 2023

Thanks s3v

@kloczek
Copy link
Author

kloczek commented Nov 5, 2023

@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.

extra_extensions=[],

@kloczek
Copy link
Author

kloczek commented Apr 6, 2024

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants