Documentation cleanup

[kwohlfahrt]

Original bug: Pulling random lines out of the tests in doc doesn't cause python3 runtests.py to fail. Tests in function docstrings are picked up (at least as of #163).

Update: It looks like there are a lot of documentation/doctest cleanups to be done.

• Consolidate "Usage Examples" (doc/source/regression) and demo
  • The "Usage Examples" page was the only tests, now we have unit tests. They should be edited to be better examples.
  • The demo folder is untested, so they should be migrated to the documentation and tested with doctest.
• Include doctests in CI
• Consolidate API reference and docstrings
  • Most of the API reference pages duplicate docstrings, so they can be merged.

Minor issues:

• Clean up release notes
  • Currently the ones in doc/source just include the ones in doc/release, unnecessary clutter
• Add status badge for AppVeyor
• Remove PyWavelets table of contents page (basically just a link to an expanded table of contents)
• Remove section about Python 3 support (doesn't need an entire section, if mentioned at all)
• Remove "Documentation" section (a link to itself, plus a mention of demo folder which will be removed)

[rgommers]

IIRC that's on purpose - the doctests in doc/ were the only form of tests before I started working on pywt. Now those should be translated to unit tests. Not sure they're all translated (haven't checked), but would be good to get rid of these doctests because (a) they're duplicate, and (b) they're pretty poor for actual documentation.

[kwohlfahrt]

OK, changing the issue title, looks like there's a lot to be done about documentation (sigh). I've made a list in the original report, feel free to mention any other issues and I'll update it.

[kwohlfahrt]

Notes on doc/source/regression. I found the chapters on wavelet packets to be much more useful than the API documentation, so there is some value in them. Perhaps a "Getting started" chapter wouldn't be amiss.

Current contents:

• dwt-idwt.rst
  • round-trip 1D dwt
  • dwt_coeff_len
  • Available modes and dwt_coeff_len for each mode
  • use of None as idwt parameter
  • Error on unequal coeff len
  • error on coeffs too short for provided mode + wavelet
• gotchas.rst
  • None -> NaN conversion
• modes.rst
  • test availability of modes
  • test invalid mode error
  • test default mode
  • test reconstruction for each mode
• multilevel.rst
  • check output values for wavedec
  • check output length for specific level wavedec
  • check reconstruction
  • Ditto for SWT
• wavelet.rst
  • Show families, number of wavelets
  • construction
  • printing of wavelet
  • show filter coefficients, w.filter_bank
  • show other properties
  • show creation of custom wavelet and setting properties
  • explain wavefun (and different # of coefficients returned)
• wp.rst
  • create wavelet packets
  • indexing, errors on invalid/too long index
  • show nodes at a particular level (and sorting)
  • show deletion of nodes affecting reconstruction
• wp2d.rst
  • as wp.rst, but 2D. Uses some diagrams to illustrate vahd names for indices.

Ideas for re-structuring

1. Wavelets
   • Explain wavelet contents (filter bank, metadata)
   • Show availability of builtin wavelets
   • Show creation of custom wavelets
   • Explain plotting of wavefun (and how this is constructed)
2. Transforms
   • Brief explanation of approximation and detail coefficients
   • Explain the general naming scheme of (i)[d/s]wt([2/n]). Brief overview of difference between d and s wt.
   • Refer to API documentation for exact output format
   • Refer to API documentation for extension modes
   • Mention use of None (and gotcha that a list containing None -> NaN)
3. Multilevel
   • Demonstrate doing multilevel by hand
   • Show multilevel as short version, explain difference for odd-length data
4. Wavelet packets
   • Can probably be kept more-or-less as-is. Though I'm not entirely sure what their point is at the moment, this should probably be explained

[kwohlfahrt]

Notes on demo

• benchmark.py: benchmark for several sizes and wavelet of 1D transform
  • I don't think this needs to be preserved, fairly self explanatory
• dwt2_dwtn_image.py: Show round-trip of pywt.data.aero(), including difference of dwt2/dwtn API
  • This is covered by the API documentation, though a detailed example wouldn't be amiss
• dwt_signal_decomposition: decomposes a signal 5 times with dwt (line with changing gradient, sine with changing frequency, ECG) and then plots each level of reconstruction.
  • looks like this was written before wavedec/rec?
  • Should be merged into documentation of multilevel examples
• dwt_swt_show_coeffs: as above, but with both swt and dwt. Doesn't do the reconstruction, only shows coeffs as they are being deconstructed (not sure why the above does).
  • As above
• plot_wavelets.py: plots wavefun for a whole bunch of available wavelets
  • Merge into general documentation about wavelets
• swt2.py: Plots coefficients at a few different levels
  • again, mostly covered by the API documentation but a few examples might be useful
• waveinfo.py: Plots wavefun for a specific wavelet
  • same as plot_wavelets.py
• wp_2d.py: Plot coefficients for a wavelet packet transform
  • Merge into wavelet packet docs
• image_blender.py: TODO
• wp_scalogram.py: TODO
• wp_visualize_coeffs_distribution.py: TODO

[kwohlfahrt]

@rgommers: Do you know what the demo/dwt_signal_decomposition.py demo is showing? I understand the decomposition part, but then before plotting it runs the coefficients through waverec. If this is a common pattern I'd like to document it properly in the examples.

[grlee77]

@kwohlfahrt: I know it has been a long time since this was originally asked, but the use of waverecn with None for the detail coefficients (and [None, None] for additional levels) is equivalent to using all zeros for detail coefficients. This is a way to upsample the approximation coefficients at each level to have approximately the same number of samples as the original signal in demo/dwt_signal_decomposition.py.

Here is a link to a section in Matlab's documentation which discusses this sort of thing (see the section titled Reconstructing Approximations and Details):
https://www.mathworks.com/help/wavelet/gs/wavelet-reconstruction.html

I checked the box above for "Include doctests in CI" as that was recently implemented in #210