Skip to content

Conversation

@kekedy0212-design
Copy link

@kekedy0212-design kekedy0212-design commented Dec 8, 2025

This PR addresses Issue #20077 by merging the two separate error code documentation pages (error_code_list.rst and error_code_list2.rst) into a single, unified document. This improves the user experience by eliminating the need to guess and navigate between two different pages when looking up an error code.

Changes made:

  1. Created a new unified file: docs/source/error_codes_merged.rst
  2. Enhanced clarity: Added explicit **Default enabled:** Yes or **Default enabled:** No annotation to every error code entry, making this crucial information immediately visible.
  3. Updated navigation: Modified docs/source/index.rst to reference the new unified file instead of the two separate ones.
  4. Cleaned up: Removed the now-redundant error_code_list.rst and error_code_list2.rst files.

Benefits:

  • Users can now find any error code and know its default status from a single page.
  • Solves the exact problem described in the issue: “half the time I end up checking the wrong page”.
  • The documentation structure shifts from a maintainer-centric split to a user-centric unified list.

Fixes #20077

@kekedy0212-design
Copy link
Author

kekedy0212-design commented Dec 9, 2025

Hi maintainers, note that the conflict warning is likely because the file error_code_list.rst has been removed on both sides. The changes are semantically clean (merging two lists into one). Thanks for reviewing!

@wyattscarpenter
Copy link
Contributor

wyattscarpenter commented Dec 10, 2025

@kekedy0212-design I'm not a maintainer, but that's not really what the "merge conflict" warning... demands. The "merge conflict" is about merging git commits, a git operation, not about "merging" the files as we've done here. The problem is probably that the master branch of mypy has some change to error_code_list.rst or error_code_list2.rst, that happened since you started working on this PR (in terms of git branches), and so git doesn't know what it should do if this PR is accepted. In particular, since the finished state is unknown, the CI cannot run on that either.

You should be the one to fix this error. Technically a maintainer could fix it for you; they have the power to if you've selected the right setting on the PR, but they tend to have other things to spend their time on. Anyway, the way to fix the merge conflict is probably by locally merge squashing your change on top of master and fixing the merge conflicts locally, then making that one commit your new branch, or something like that. Unfortunately github doesn't tell me much about the conflict in its UI so I can't tell you more than that. (That also calls into question all of the advice I gave you, frankly, as I'm just making an educated guess.) I'd offer to help you fix it, but it's probably about as much trouble for you to figure out how to cherry-pick my help via git as it is to just fix it yourself 😄

You should probably mark this PR as draft until you do fix that.

@wyattscarpenter
Copy link
Contributor

wyattscarpenter commented Dec 10, 2025

There are some other things I'd like to see in this PR:

Easy: instead of calling it error_codes_merged.rst, call it error_codes.rst. Make the current error_codes.rst simply a preamble to this file (possibly this will work with mere concatenation).

Hard: figure out sphinx redirects so that someone trying to visit, say, https://mypy.readthedocs.io/en/stable/error_code_list2.html#check-that-type-arguments-exist-type-arg (which is a heading on a page that will no longer exist) will be redirected to the right page and heading instead.

I have not reviewed the listings of the merged file for correctness.

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

Successfully merging this pull request may close these issues.

[docs] merge error code lists

2 participants