LibCST
LibCST copied to clipboard
Pinned on a heavily outdated Sphinx fork is causing at least 138 errors in the document
While reading libcst document, I notice that there are some confusing discrepancies in the document:
- The
visit()
method oflibcst.CSTNode
is shown to be a zero-argument function. 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. - The
libcst.helpers.ensure_type()
is shown to be a zero-argument function, which is definitely confusing. - The
findall/extract/extractall/replace
functions in thelibcst.matchers
module are all shown to be zero-argument 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. 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 to build document, is an old personal fork, 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.