import warnings: syntax & deprecation #891
Labels
Comments
|
Thanks for the report |
guyer
added a commit
that referenced
this issue
Sep 6, 2023
guyer
added a commit
that referenced
this issue
Oct 6, 2023
* Guard examples against running on import
Examples should not run when building docs
* Change paths so Sphinx builds canonically in documentation/ dir
* Account for NaN deviation in plots
Single points have no standard deviation? Used to work, but no more
* Move index files to Sphinx source directory
* Move Sphinx content into Sphinx source directory
* Rename AbstractCommWrapper to CommWrapper
* Move figures into Sphinx source directory
* Remove py:attr reference to target `self.vars[0]`
* Fix name of `array_like`
* Fix deprecations
* Fix targets in doc strings
* Fix typos
* Add base classes to `__all__` for documentation cross-links
* Fix name of base class
* Stop indexing explicit examples
Some examples now appear in two locations
[TODO: Sorting that out is misery for another day]
- in the explicit list of examples
- in the examples API documentation
Loud warnings if we try to index both, so only index the API variant.
* Simplify API toctree
* Clear up root of examples documentation
* Fix tutorial documentation toctree
* Add mock imports for solvers that probably aren't installed
* Update intersphinx mappings
* Stop generating autosummary for examples
Examples are referred to explicitly and in API.
Don't need autosummary, too?
* Fix broken links
* Remove references to obsolete classes
* Make module name legal
* Fix typo
* Fix target type
* Make labels unique
* Link to examples in API documentation
Removes duplicate entries
* Explicitly denote "single" index entries
The
["shorthand" notation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-index)
raises lots of spurious warnings about
`Explicit markup ends without a blank line; unexpected unindent.`
* Fix path to included file
* Ignore modules file
* Specify attribute path
* Fix markup of combined attribute
* Fix duplicate footnotes
* Update instructions for building documentation
Much changes when using Sphinx's canonical `make html`.
* Remove build_docs command from setup
* Stop hiding api docs
* Fix crosslink to updating instructions
* Fix broken links
* Fully specify inherited object to document
* Mute Mayavi documentation issues
* Fix target reference for factory method
* Move ElPhF documentation from TeX to module docstring
* Change target type for Python standard types
:keyword:`dict` links to
https://docs.python.org/3/reference/expressions.html#dict
but :keyword:`list` doesn't link to
https://docs.python.org/3/reference/expressions.html#list-displays
?
:class:`dict`, :class:`list`, and :class:`tuple` are more
appropriate, anyway.
* Don't nitpick references to files and the like
* Remove arcane `__all__.extend`
Rely on public imports for public API
* Distinguish pyAMG LU from SciPy LU
* Fix references to objects no longer in Brobdingnagian `__all__`
* Document generic solver classes
* Activate de-coupled binary phase field example
* Fix LaTeX glitches of long standing
* Migrate machinery from for turning .rst into .tex inputs
Not sure this belongs in conf.py,
but don't know where else it belongs
* Move LaTeX formatting into a .sty file
* Move documentation into separated layout
Separate source and build directories is what
[Sphinx seems to prefer](https://www.sphinx-doc.org/en/master/tutorial/getting-started.html#creating-the-
documentation-layout).
* Wrap lines and have apidoc process examples
* Point workflow to new location of docs
* Update action inputs
* Move requirements.txt into docs folder
This is where sphinx-action (and, now, NISTtheDocs2Death)
are looking for it.
* Create directory for generated output
* Wrap commands with parentheses
* Use line-continuing backslashes
* Require fipy in order to build fipy docs
* Look for packages one level up
* Remove obsolete action input
* Switch API documentation to autosummary
* Change imports to avoid Sphinx bug
Importing part of a package within itself causes
[autosummary weirdities](sphinx-doc/sphinx#8963)
* Move docstring to class from __init__
Shouldn't be necessary, because `autoclass_content = "both"` is set...
* Update version
* Install git
* Bump version of ntd2d
* Skip numpy 1.25 dispatch functions
* Silence Sphinx autosummary errors
Documented some items, hid others.
`autosummary <https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html>`_
and/or `autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_
really didn't like "`matplotlibViewer/matplotlibViewer`".
Possibly related to sphinx-doc/sphinx#11362 ?
* Add module docstrings
* Add pip requirements
* Stop building docs (badly) on Azure
* Install git with apt-packages
* Make workdirectory a git safe.directory
* Add badges for GH Actions
* Remove Codacy badge
Codacy is no longer free
* Fix conda-forge badge
* Switch docs pre-requisites to conda
* Update badges on static index.html
* Install self with conda from parent directory
* Fix reST
* Remove depsy badge
Project hasn't been maintained in five years and badge is broken
(because it's only available as an http:// link in an https:// page?)
* Add mock imports for petsc4py, mpi4py, and mayavi
* Update searchbox to be consistent with basic theme
* Add more mock imports
* Add intersphinx mapping for mayavi
* Stop using "is" and "is not" to compare with literals
Addresses #891
* Fix spelling
* Fix renaming missed in 819fbfa
* Switch from mamba to conda in Py2.7
* Ensure logging is configured
* Fix unicode module contents for Py2.7
* Fix typo
Co-authored-by: Trevor Keller <trevor.keller@nist.gov>
* Add brief explanation of each chunk of examples
* Make multiline pre-build-command "chomping"
* Convert rst to tex with make
* Generate PDF
* Remove file conversion from configuration
* Make Makefile more makey
* Collapse examples into a single chapter
Co-authored-by: Trevor Keller <trevor.keller@nist.gov>
guyer
added a commit
that referenced
this issue
Oct 6, 2023
Clean up legacy Sphinx hacks and resolve longstanding warnings. Support use of NISTtheDocs2Death to put documentation on https://pages.nist.gov/fipy. Previous configuration went to great lengths to "see" things outside documentation directory, which is not the intended design of sphinx. Using autodoc instead of autosummary simplifies things considerably. * Guard examples against running on import Examples should not run when building docs * Change paths so Sphinx builds canonically in documentation/ dir * Account for NaN deviation in plots Single points have no standard deviation? Used to work, but no more * Move index files to Sphinx source directory * Move Sphinx content into Sphinx source directory * Rename AbstractCommWrapper to CommWrapper * Move figures into Sphinx source directory * Remove py:attr reference to target `self.vars[0]` * Fix name of `array_like` * Fix deprecations * Fix targets in doc strings * Fix typos * Add base classes to `__all__` for documentation cross-links * Fix name of base class * Stop indexing explicit examples Some examples now appear in two locations [TODO: Sorting that out is misery for another day] - in the explicit list of examples - in the examples API documentation Loud warnings if we try to index both, so only index the API variant. * Simplify API toctree * Clear up root of examples documentation * Fix tutorial documentation toctree * Add mock imports for solvers that probably aren't installed * Update intersphinx mappings * Stop generating autosummary for examples Examples are referred to explicitly and in API. Don't need autosummary, too? * Fix broken links * Remove references to obsolete classes * Make module name legal * Fix typo * Fix target type * Make labels unique * Link to examples in API documentation Removes duplicate entries * Explicitly denote "single" index entries The ["shorthand" notation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-index) raises lots of spurious warnings about `Explicit markup ends without a blank line; unexpected unindent.` * Fix path to included file * Ignore modules file * Specify attribute path * Fix markup of combined attribute * Fix duplicate footnotes * Update instructions for building documentation Much changes when using Sphinx's canonical `make html`. * Remove build_docs command from setup * Stop hiding api docs * Fix crosslink to updating instructions * Fix broken links * Fully specify inherited object to document * Mute Mayavi documentation issues * Fix target reference for factory method * Move ElPhF documentation from TeX to module docstring * Change target type for Python standard types :keyword:`dict` links to https://docs.python.org/3/reference/expressions.html#dict but :keyword:`list` doesn't link to https://docs.python.org/3/reference/expressions.html#list-displays ? :class:`dict`, :class:`list`, and :class:`tuple` are more appropriate, anyway. * Don't nitpick references to files and the like * Remove arcane `__all__.extend` Rely on public imports for public API * Distinguish pyAMG LU from SciPy LU * Fix references to objects no longer in Brobdingnagian `__all__` * Document generic solver classes * Activate de-coupled binary phase field example * Fix LaTeX glitches of long standing * Migrate machinery from for turning .rst into .tex inputs Not sure this belongs in conf.py, but don't know where else it belongs * Move LaTeX formatting into a .sty file * Move documentation into separated layout Separate source and build directories is what [Sphinx seems to prefer](https://www.sphinx-doc.org/en/master/tutorial/getting-started.html#creating-the- documentation-layout). * Wrap lines and have apidoc process examples * Point workflow to new location of docs * Update action inputs * Move requirements.txt into docs folder This is where sphinx-action (and, now, NISTtheDocs2Death) are looking for it. * Create directory for generated output * Wrap commands with parentheses * Use line-continuing backslashes * Require fipy in order to build fipy docs * Look for packages one level up * Remove obsolete action input * Switch API documentation to autosummary * Change imports to avoid Sphinx bug Importing part of a package within itself causes [autosummary weirdities](sphinx-doc/sphinx#8963) * Move docstring to class from __init__ Shouldn't be necessary, because `autoclass_content = "both"` is set... * Update version * Install git * Bump version of ntd2d * Skip numpy 1.25 dispatch functions * Silence Sphinx autosummary errors Documented some items, hid others. `autosummary <https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html>`_ and/or `autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_ really didn't like "`matplotlibViewer/matplotlibViewer`". Possibly related to sphinx-doc/sphinx#11362 ? * Add module docstrings * Add pip requirements * Stop building docs (badly) on Azure * Install git with apt-packages * Make workdirectory a git safe.directory * Add badges for GH Actions * Remove Codacy badge Codacy is no longer free * Fix conda-forge badge * Switch docs pre-requisites to conda * Update badges on static index.html * Install self with conda from parent directory * Fix reST * Remove depsy badge Project hasn't been maintained in five years and badge is broken (because it's only available as an http:// link in an https:// page?) * Add mock imports for petsc4py, mpi4py, and mayavi * Update searchbox to be consistent with basic theme * Add more mock imports * Add intersphinx mapping for mayavi * Stop using "is" and "is not" to compare with literals Addresses #891 * Fix spelling * Fix renaming missed in 819fbfa * Switch from mamba to conda in Py2.7 * Ensure logging is configured * Fix unicode module contents for Py2.7 * Fix typo Co-authored-by: Trevor Keller <trevor.keller@nist.gov> * Add brief explanation of each chunk of examples * Make multiline pre-build-command "chomping" * Convert rst to tex with make * Generate PDF * Remove file conversion from configuration * Make Makefile more makey * Collapse examples into a single chapter Co-authored-by: Trevor Keller <trevor.keller@nist.gov>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Running FiPy on Python 3.9 in a Jupyter notebook, some routine imports throw warnings that would be nice to clear up.
SyntaxWarning: "is not"/"is" with a literal. Did you mean "!="/"=="?Looks like
isis supported forNonebut not most useful things, which is a bummer for readability.variables/variable.py:649variables/meshVariable.py:118variables/meshVariable.py:523meshes/abstractMesh.py:1148meshes/uniformGrid2D.py:428terms/abstractConvectionTerm.py:155DeprecationWarning: invalid escape sequence {\c,\m,\p}Not very important, but these are thrown from docstrings with math notation, apparently parsing the
"""-delimited blocks as code instead of comments. Rude.boundaryConditions/boundaryCondition.py:45The text was updated successfully, but these errors were encountered: