Repository navigation
DOC: Remove the spurious warnings from the Sphinx build - #767
Merged
Merged
Conversation
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 Report✅ All modified and coverable lines are covered by tests. 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
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.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.
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.
class is documented in linearmodels.shared.hypotheses.
pesaran_cd returns.
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.
np.ndarray pointed to numpy.array and now points to numpy.ndarray.
_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.
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.
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.