Skip to content

DOC: Remove the spurious warnings from the Sphinx build - #767

Merged
bashtage merged 5 commits into
mainfrom
lm71-doc2-docs-build
Oct 12, 2026
Merged

bashtage merged 5 commits into
mainfrom
lm71-doc2-docs-build

Conversation

@bashtage

Copy link
Copy Markdown
Owner

The documentation build of main (121d869) ends with "build succeeded, 521
warnings" (533 in the last run on GitHub Actions, 37955470056; the footnotes of
the rank tests have been fixed since). With this change the same build ends
with "build succeeded, 3 warnings", with the packages of the CI run (Sphinx
9.1.0, sphinx-immaterial 0.13.9) on Linux with "-j 4", on Python 3.13 and 3.14.
The 3 that remain are in docstrings and belong to the docstring work: the type
list[str] in the docstrings of param_names in system/model.py.

Only doc/source/conf.py and doc/source/nitpick-exceptions change. The 521:

  • NumPy scalars, 438 (numpy.float64 388, numpy.int64 48, numpy.int32 1,
    numpy.uint32 1). The array aliases expand in the signatures to
    ndarray[tuple[int, ...], dtype[float64]], and NumPy documents its scalar
    types as attributes, so the lookup of a class never succeeds. They are in
    nitpick-exceptions. The dtype stays in the signature, without a link.
  • TypeAliasForwardRef 44 (188 in a serial build), pd.DataFrame 2 and pd.Series
    2. When a class docstring has a parameter without a type, napoleon in
    Sphinx 9 looks for the annotation of that name in the class and, as a side
    effect, merges napoleon_type_aliases into autodoc_type_aliases in place.
    From then on a nested annotation such as "DataFrame | None" is shown as
    "TypeAliasForwardRef('pandas.DataFrame') | None" with a warning that the
    class does not exist, and the dotted alias "pd.Series" turns pd into a
    pseudo module, so that "pd.DataFrame" cannot be evaluated and is shown as
    text. The signatures that are affected depend on the order in which the pages
    are built, which is why a parallel and a serial build disagree.
    napoleon_attr_annotations = False stops the lookup. The signatures are now
    shown like all others, and the types link to the pandas, NumPy and
    linearmodels documentation. The ndarray in the signature of LinearConstraint
    no longer links to IVData.ndarray.
  • InvalidTestStatistic, 6. The alias pointed to linearmodels.shared, but the
    class is documented in linearmodels.shared.hypotheses.
  • InapplicableTestStatistic, 4. It had no alias, and it is the type that
    pesaran_cd returns.
  • DataFrame, 10. The signatures of the NamedTuples PanelModelData (8) and
    HausmanTestResults (2) show the bare name, because autodoc cannot evaluate
    the annotations of the new that NamedTuple generates. The
    python_type_aliases option of sphinx-immaterial expands it to
    pandas.DataFrame.
  • csc_array, 1. Added with csr_array and coo_array to the aliases. The alias
    np.ndarray pointed to numpy.array and now points to numpy.ndarray.
  • Private and undocumented classes, 8, which are in nitpick-exceptions: the
    _IVModelBase and _IVGMMBase in the annotations of the results classes (6),
    the protocol SupportsKeysAndGetItem of AttrDict.update (1), and the :class:
    role for functools.cached_property in changes/5.0.rst (1), which the Python
    documentation lists as a function. The exception for IVDataLike is removed
    because nothing refers to it any more.
  • AttrDict, 3. get, popitem and setdefault are inherited from
    collections.abc.MutableMapping. Their docstrings are not numpydoc, and
    napoleon turns them into cross-references to types that do not exist. A
    handler of autodoc-skip-member leaves out the members of collections.abc, so
    these three are no longer documented as methods of AttrDict.
  • list[str], 3, which stay. The docstring rules write "list of str".

napoleon_type_aliases and numpydoc_xref_aliases were copies of each other with
the same mistakes. They are now built from one dictionary. numpydoc is not in
extensions, so its options still have no effect. Aliases are added for
HausmanTestResults, AbsorbingLS and FamaMacBethResults, so that every estimator
and results class has one, and for callable, scalar and sequence, which the
docstring rules use and which resolve to the glossaries of Python and NumPy.

ipykernel 7 also prints "Kernel is running over TCP without encryption" once
for each notebook that nbsphinx runs, 12 in the CI log. They are not counted in
the 521, but they look like warnings. nbsphinx_execute_arguments sets the
kernel log level to ERROR.

To reproduce the CI build, install the packages of the CI run and run, from
doc/, "sphinx-build -M html source build -j 4". Pandoc is needed to convert
the notebooks.

The documentation build of main (121d869) ends with "build succeeded, 521
warnings" (533 in the last run on GitHub Actions, 37955470056; the footnotes of
the rank tests have been fixed since). With this change the same build ends
with "build succeeded, 3 warnings", with the packages of the CI run (Sphinx
9.1.0, sphinx-immaterial 0.13.9) on Linux with "-j 4", on Python 3.13 and 3.14.
The 3 that remain are in docstrings and belong to the docstring work: the type
list[str] in the docstrings of param_names in system/model.py.

Only doc/source/conf.py and doc/source/nitpick-exceptions change. The 521:

* NumPy scalars, 438 (numpy.float64 388, numpy.int64 48, numpy.int32 1,
  numpy.uint32 1). The array aliases expand in the signatures to
  ndarray[tuple[int, ...], dtype[float64]], and NumPy documents its scalar
  types as attributes, so the lookup of a class never succeeds. They are in
  nitpick-exceptions. The dtype stays in the signature, without a link.
* TypeAliasForwardRef 44 (188 in a serial build), pd.DataFrame 2 and pd.Series
  2. When a class docstring has a parameter without a type, napoleon in
  Sphinx 9 looks for the annotation of that name in the class and, as a side
  effect, merges napoleon_type_aliases into autodoc_type_aliases in place.
  From then on a nested annotation such as "DataFrame | None" is shown as
  "TypeAliasForwardRef('pandas.DataFrame') | None" with a warning that the
  class does not exist, and the dotted alias "pd.Series" turns pd into a
  pseudo module, so that "pd.DataFrame" cannot be evaluated and is shown as
  text. The signatures that are affected depend on the order in which the pages
  are built, which is why a parallel and a serial build disagree.
  napoleon_attr_annotations = False stops the lookup. The signatures are now
  shown like all others, and the types link to the pandas, NumPy and
  linearmodels documentation. The ndarray in the signature of LinearConstraint
  no longer links to IVData.ndarray.
* InvalidTestStatistic, 6. The alias pointed to linearmodels.shared, but the
  class is documented in linearmodels.shared.hypotheses.
* InapplicableTestStatistic, 4. It had no alias, and it is the type that
  pesaran_cd returns.
* DataFrame, 10. The signatures of the NamedTuples PanelModelData (8) and
  HausmanTestResults (2) show the bare name, because autodoc cannot evaluate
  the annotations of the __new__ that NamedTuple generates. The
  python_type_aliases option of sphinx-immaterial expands it to
  pandas.DataFrame.
* csc_array, 1. Added with csr_array and coo_array to the aliases. The alias
  np.ndarray pointed to numpy.array and now points to numpy.ndarray.
* Private and undocumented classes, 8, which are in nitpick-exceptions: the
  _IVModelBase and _IVGMMBase in the annotations of the results classes (6),
  the protocol SupportsKeysAndGetItem of AttrDict.update (1), and the :class:
  role for functools.cached_property in changes/5.0.rst (1), which the Python
  documentation lists as a function. The exception for IVDataLike is removed
  because nothing refers to it any more.
* AttrDict, 3. get, popitem and setdefault are inherited from
  collections.abc.MutableMapping. Their docstrings are not numpydoc, and
  napoleon turns them into cross-references to types that do not exist. A
  handler of autodoc-skip-member leaves out the members of collections.abc, so
  these three are no longer documented as methods of AttrDict.
* list[str], 3, which stay. The docstring rules write "list of str".

napoleon_type_aliases and numpydoc_xref_aliases were copies of each other with
the same mistakes. They are now built from one dictionary. numpydoc is not in
extensions, so its options still have no effect. Aliases are added for
HausmanTestResults, AbsorbingLS and FamaMacBethResults, so that every estimator
and results class has one, and for callable, scalar and sequence, which the
docstring rules use and which resolve to the glossaries of Python and NumPy.

ipykernel 7 also prints "Kernel is running over TCP without encryption" once
for each notebook that nbsphinx runs, 12 in the CI log. They are not counted in
the 521, but they look like warnings. nbsphinx_execute_arguments sets the
kernel log level to ERROR.

To reproduce the CI build, install the packages of the CI run and run, from
doc/, "sphinx-build -M html source build -j 4". Pandoc is needed to convert
the notebooks.
The footer of the documentation says "Copyright 2021, Kevin Sheppard", but the
package has been released since 2017 (LICENSE.md also says 2017). It now says
2017 to the year in which the documentation is built. Sphinx replaces the last
year when SOURCE_DATE_EPOCH is set, so builds with that variable stay
reproducible.
changes.rst gives the title "Past Releases" an overline and an underline. No
other title has that style, so docutils takes it for a new level below the
deepest one used so far, and the heading becomes a subsection of the last
section above it: on the published page it is an h3 inside "Version 7.0".
Subsections in the included notes would push it down even further, which is
why the 7.1 notes use rubrics instead of sections.

With an underline of dashes, like the versions, "Past Releases" is a section of
the same level as "Version 7.1" and "Version 7.0", which end the included
notes, and the notes are free to use sections of their own. The page builds
with no new warning and the home page does not change. An underline of equals
signs, the style of "Change Log", would also work but would add "Past
Releases" to the home page as a second top-level entry of the page.
"sphinx-build -b spelling" reports 189 misspelled words, 52 different ones, in
the documentation of main. Nearly all of them come from the text of 7.1. After
this change 3 reports remain, for the 2 words that are mistakes in the text.

names_wordlist.txt:

* the authors and the journal cited by the new docstrings: Pesaran, Juodis,
  Angrist, Chao, Imbens, Krueger, Woutersen, Hayashi and Econometrica
* the same names as they are written in function names (cragg_donald,
  kleibergen_paap, pesaran_cd), because the lower case form of a word is not
  accepted when only the capitalised form is listed
* the GitHub user names in the contributors of the 7.1 release notes

spelling_wordlist.txt:

* the classes that are new or that were never in the list and that appear in
  the titles of the reference pages: GMMFactorModelResults, IVJIVE, OLS,
  PanelModelData, AbsorbingRegressor, HausmanTestResults,
  InapplicableTestStatistic, LinearConstraint and NormalTestStatistic
* statsmodels, compat, csv, html, txt, gleft, gright, xname, yname and num,
  which are in the names of the Summary methods and their arguments
* nan, rc (NumPy 2.0.0rc1), ranktest (a Stata module) and the words
  autocorrelated, misspecification, partialled (used 9 times in the package),
  regressors, reindex, docstring and numpydoc

Two words stay on the list of the spelling builder on purpose, because they are
mistakes to fix in the text and not words to accept: "rsquare" in the
docstrings of FamaMacBethResults.avg_rsquared and avg_adj_rsquared, and "fuure"
in changes/6.0.rst.
Every docs build writes the autosummary pages of compatibility.rst,
utility.rst and the AbsorbingLS section of iv/reference.rst into
doc/source/compatibility/, doc/source/utility/ and doc/source/iv/absorbing/.
.gitignore covered the folders of the other reference pages but not these
three, so a local build left them as untracked files.
@codecov

codecov Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.60%. Comparing base (121d869) to head (0a9c90b).
⚠️ Report is 10 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main     #767   +/-   ##
=======================================
  Coverage   99.60%   99.60%           
=======================================
  Files         127      127           
  Lines       23832    23832           
  Branches     1783     1783           
=======================================
  Hits        23737    23737           
  Misses         35       35           
  Partials       60       60           
Flag Coverage Δ
adder 99.58% <ø> (ø)
subtractor 99.58% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@bashtage
bashtage merged commit 6cbd30b into main Oct 12, 2026
20 of 24 checks passed
@bashtage
bashtage deleted the lm71-doc2-docs-build branch October 12, 2026 09:21
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.

1 participant