LibCST icon indicating copy to clipboard operation
LibCST copied to clipboard

Pinned on a heavily outdated Sphinx fork is causing at least 138 errors in the document

Open MapleCCC opened this issue 2 years ago • 0 comments

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. 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, which is definitely confusing.
  3. The findall/extract/extractall/replace functions in the libcst.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.

MapleCCC avatar Aug 16 '22 22:08 MapleCCC