sphinx-doc / sphinx-doc/sphinx

Manual pages build fails

Open
#9,869 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug

The execution of the command make man with the default Sphinx Makefile fails with an AssertionError.

How to Reproduce
$ git clone https://github.com/ragonneau/cobyqa.git
$ cd cobyqa/docs
$ pip install -r requirements.txt
$ make man
Expected behavior

The man pages to be built.

Your project

https://github.com/ragonneau/cobyqa

Screenshots
# Sphinx version: 4.3.0
# Python version: 3.9.5 (CPython)
# Docutils version: 0.17.1 release
# Jinja2 version: 3.0.3
# Last messages:
#   refs/generated/cobyqa.linalg.nnls
#   refs/generated/cobyqa.linalg.rot
#   refs/generated/cobyqa.linalg.rotg
#   refs/tests
#   refs/generated/cobyqa.tests.assert_array_less_equal
#   refs/generated/cobyqa.tests.assert_dtype_equal
#   bugs
#   license
#   }
#   failed
# Loaded extensions:
#   sphinx.ext.mathjax (4.3.0) from /home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/ext/mathjax.py
#   sphinxcontrib.applehelp (1.0.2) from /home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinxcontrib/applehelp/__init__.py
#   sphinxcontrib.devhelp (1.0.2) from /home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinxcontrib/devhelp/__init__.py
#   sphinxcontrib.htmlhelp (2.0.0) from /home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinxcontrib/htmlhelp/__init__.py
#   sphinxcontrib.serializinghtml (1.1.5) from /home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinxcontrib/serializinghtml/__init__.py
#   sphinxcontrib.qthelp (1.0.3) from /home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinxcontrib/qthelp/__init__.py
#   alabaster (0.7.12) from /home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/alabaster/__init__.py
#   sphinx.ext.autodoc.preserve_defaults (1.0) from /home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/ext/autodoc/preserve_defaults.py
#   sphinx.ext.autodoc.type_comment (4.3.0) from /home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/ext/autodoc/type_comment.py
#   sphinx.ext.autodoc (4.3.0) from /home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/ext/autodoc/__init__.py
#   sphinx.ext.autosummary (4.3.0) from /home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/ext/autosummary/__init__.py
#   numpydoc (1.1.0) from /home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/numpydoc/__init__.py
#   sphinx.ext.doctest (4.3.0) from /home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/ext/doctest.py
#   sphinx.ext.intersphinx (4.3.0) from /home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/ext/intersphinx.py
#   sphinx.ext.linkcode (4.3.0) from /home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/ext/linkcode.py
#   sphinxcontrib.bibtex (2.4.1) from /home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinxcontrib/bibtex/__init__.py
Traceback (most recent call last):
  File "/home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/cmd/build.py", line 280, in build_main
    app.build(args.force_all, filenames)
  File "/home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/application.py", line 344, in build
    self.builder.build_update()
  File "/home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 291, in build_update
    self.build(['__all__'], to_build)
  File "/home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 358, in build
    self.write(docnames, list(updated_docnames), method)
  File "/home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/util/__init__.py", line 547, in wrapper
    return f(*args, **kwargs)
  File "/home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/builders/manpage.py", line 99, in write
    self.env.resolve_references(largetree, docname, self)
  File "/home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/environment/__init__.py", line 569, in resolve_references
    self.apply_post_transforms(doctree, fromdocname)
  File "/home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/environment/__init__.py", line 581, in apply_post_transforms
    transformer.apply_transforms()
  File "/home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/transforms/__init__.py", line 86, in apply_transforms
    super().apply_transforms()
  File "/home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/docutils/transforms/__init__.py", line 171, in apply_transforms
    transform.apply(**kwargs)
  File "/home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/transforms/post_transforms/__init__.py", line 43, in apply
    self.run(**kwargs)
  File "/home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/sphinx/transforms/post_transforms/__init__.py", line 121, in run
    node.replace_self(newnodes)
  File "/home/tmr/PycharmProjects/cobyqa/venv/lib/python3.9/site-packages/docutils/nodes.py", line 1034, in replace_self
    assert not self[att], \
AssertionError: Losing "ids" attribute: ['id1']
OS

Linux

Python version

3.9.5

Sphinx version

4.3.0

Sphinx extensions

sphinx.ext.mathjax, sphinxcontrib.applehelp, sphinxcontrib.devhelp, sphinxcontrib.htmlhelp, sphinxcontrib.serializinghtml, sphinxcontrib.qthelp, alabaster, sphinx.ext.autodoc, sphinx.ext.autosummary, numpydoc, sphinx.ext.doctest, sphinx.ext.intersphinx, sphinx.ext.linkcode, sphinxcontrib.bibtex

Extra tools

No response

Additional context

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the failure with the documented make man command from the docs directory, then trace the assertion through sphinx/builders/manpage.py and sphinx/transforms/post_transforms/__init__.py. Done means the manual pages build successfully without the Losing "ids" attribute assertion.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
build-system, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.