Pinned on a heavily outdated Sphinx fork is causing at least 138 errors in the document
envgap__Instagram__LibCST-747
01 / FAILURE SIGNATURE
As reported upstream
No identifying execution failure has been captured.
Not a benchmark task.
- The project already builds and runs before the fix, so there is nothing to repair.
02 / ENVIRONMENT RECIPE
- Base commit
977504f10407b3d94bbe45157f9286709dd74754- Manifest
requirements-dev.txt- Reproduce
Awaiting issue-specific recipe- Run under trace
Awaiting a meaningful runtime command
03 / ORIGINAL ISSUE TEXT
Instagram/LibCST #747 · read the original issue
While reading libcst document, I notice that there are some confusing discrepancies in the document: 1. The `visit()` method of `libcst.CSTNode` is [shown to be a zero-argument function](https://libcst.readthedocs.io/en/latest/nodes.html#libcst.CSTNode.visit). However the following doc immediately states that it needs a visitor instance to operate on. An acute reader has to go to read the source code to figure out its precise usage. 2. The `libcst.helpers.ensure_type()` is [shown to be a zero-argument function](https://libcst.readthedocs.io/en/latest/helpers.html#libcst.helpers.ensure_type), which is definitely confusing. 3. The `findall/extract/extractall/replace` functions in the `libcst.matchers` module are [all shown to be zero-argument functions](https://libcst.readthedocs.io/en/latest/matchers.html#functions). It's not being helpful for readers, if not misleading. There are numerous other discrepancies in the documents. For a full list, consult the warning output of Sphinx build in the latest GitHub Action run [here](https://github.com/Instagram/LibCST/runs/7726595193?check_suite_focus=true#step:7:36). A quick counting shows that there are at least 138 errors reported in the document. I investigated the problem intensively. Turn out it has to do with how static type feature in CPython had some substantial and deeply-refactored updates on the advent of 3.9, which broke Sphinx due to its reliance on some CPython internal details. It had impacted and been reported on some other projects using Sphinx. It's a little complicated to explain all the details, but the good news is, we don't have to understand the details to fix our document. **Sphinx already fixed itself on the upstream, so what we have to do, is to just update the version of Sphinx** we use to build our document. It turns out that the version of Sphinx which LibCST [uses](https://github.com/Instagram/LibCST/blob/977504f10407b3d94bbe45157f9286709dd74754/requirements-dev.txt#L5) to build document, is an old [personal fork](https://github.com/jimmylai/sphinx), which is heavily outdated, left intact for three years, shown to be 6057 commits behind the upstream Sphinx! That reasonably explains why we are seeing all these confusing errors which should have been fixed by Sphinx around the advent of Python 3.9.
04 / LABELS
Labels from the report text only; not yet run
No supported category has been assigned.
Label rules and the text that matched
[]