Windows via conda and Doc tidy up (#12)

* windows on anaconda

* doc tidy up

.sunpy-template.yml

@@ -4,7 +4,7 @@ default_context:
   short_description: A Python wrapper for Fourier Local Correlation Tracking.
   author_name: The SunPy Developers
   author_email: sunpy@googlegroups.com
-  license: GNU GPL v3+
+  license: LGPL-2.1
   project_url: https://sunpy.org
   github_repo: sunpy/pyflct
   minimum_python_version: 3.6

README.rst

@@ -6,13 +6,28 @@ pyflct: A Python wrapper for Fourier Local Correlation Tracking.
     :target: http://www.sunpy.org
     :alt: Powered by SunPy Badge
 
-**Please be aware that we do not support Windows at the current time.**
-**Support for Python 3.6 or above only**
+pyflct is a Python wrapper around the `Fourier Local Correlation Tracking C library <http://cgem.ssl.berkeley.edu/cgi-bin/cgem/FLCT/home>`__.
+`Our built documentation is available here <https://pyflct.readthedocs.io/en/latest/>`__.
 
 Installing
 ==========
 
-If you want to install this in a work environment, please find the instructions in our documentation.
+Linux and Mac OS
+----------------
+
+The simplest way to install this library is through pip::
+
+    $ pip install pyflct
+
+This will install the pre-compiled binary wheels for these two platforms.
+
+Windows
+-------
+
+We only officially support Windows through Anaconda.
+But we do have rough instructions in our documentation if you want to install it manually.
+
+`Please find the instructions in our documentation <https://pyflct.readthedocs.io/en/latest/install.html>`__.
 
 Getting Help
 ============
@@ -22,7 +37,7 @@ Stop by our chat room `#sunpy:matrix.org`_ if you have any questions.
 Contributing
 ============
 
-If you would like to get involved, check out the `Developer’s Guide`_ section of the SunPy docs.
+If you would like to get involved, check out the `Developer's Guide`_ section of the SunPy docs.
 Help is always welcome so let us know what you like to work on, or check out the `issues page`_ for the list of known outstanding items.
 For more information on general contributing, please read our `contributing guide`_.
 
@@ -33,10 +48,10 @@ Then::
 
     $ git clone https://github.com/<username>/pyflct.git
     $ cd pyflct
-    $ pip install -e .
+    $ pip install -e .[dev]
 
 You will need to install your operating system's FFTW3 development library.
-You might need to `pip install extension_helpers` if pip complains about it being missing.
+You might need to `pip install extension_helpers` if there is an error about it being missing.
 
 You can run::
 
@@ -47,16 +62,16 @@ to build the C extension in place.
 Code of Conduct
 ===============
 
-When you are interacting with the SunPy community you are asked to follow our `Code of Conduct`_.
+When you are interacting with the SunPy community you are required to follow our `Code of Conduct.`_
 
 License
 =======
 
-This project is Copyright (c) The SunPy Developers and licensed under the terms of the GNU GPL v3+ license.
+This project is Copyright (c) The SunPy Developers and licensed under the terms of the LGPL-2.1 license.
 This package is based upon the `Openastronomy packaging guide <https://github.com/OpenAstronomy/packaging-guide>`__ which is licensed under the BSD 3-clause licence.
 
-.. _`Developer’s Guide`: https://docs.sunpy.org/en/latest/dev_guide/index.html
+.. _`Developer's Guide`: https://docs.sunpy.org/en/latest/dev_guide/index.html
 .. _`#sunpy:matrix.org`: https://riot.im/app/#/room/#sunpy:matrix.org
 .. _issues page: https://github.com/sunpy/pyflct/issues
 .. _contributing guide: https://docs.sunpy.org/en/latest/dev_guide/newcomers.html#newcomers
-.. _Code of Conduct: https://docs.sunpy.org/en/stable/coc.html
+.. _Code of Conduct.: https://docs.sunpy.org/en/stable/coc.html

azure-pipelines.yml

@@ -44,8 +44,8 @@ jobs:
       - macos: py36
         name: py36_test
 
-      - windows: conda
-        name: win_conda
+      - windows: py38-conda
+        name: py38_conda
 
       - linux: py37
         name: py37_test
@@ -66,7 +66,7 @@ jobs:
       libraries:
         - libfftw3-dev
       test_extras: 'test'
-      test_command: 'pytest -p no:warnings --doctest-rst -m "not figure" --pyargs pyflct'
+      test_command: 'pytest --pyargs pyflct'
       submodules: false
       targets:
         - wheels_linux

cextern/COPYRIGHT

@@ -1,6 +1,7 @@
+
 /*
        FLCT Local Correlation Tracking software
-       http://cgem.ssl.berkeley.edu/~fisher/public/software/FLCT
+       http://cgem.ssl.berkeley.edu/cgi-bin/cgem/FLCT/home
        Copyright (C) 2007-2019, Regents of the University of California
 
        This software is based on the concepts described in Welsch & Fisher

docs/conf.py

@@ -8,7 +8,9 @@
 # -- Project information -----------------------------------------------------
 import os
 from pathlib import Path
+
 from pyflct import __version__
+
 project = "pyflct"
 copyright = "2020, The SunPy Developers"
 author = "The SunPy Developers"
@@ -20,6 +22,7 @@
 
 try:
     import sphinx_gallery
+
     sphinx_gallery.__version__
     has_sphinx_gallery = True
 except ImportError:
@@ -94,11 +97,12 @@
 # a list of builtin themes.
 
 
-def fix_circleci(x): return None
+def fix_circleci(x):
+    return None
 
 
 try:
-    from sunpy_sphinx_theme.conf import *
+    from sunpy_sphinx_theme.conf import *  # NOQA
 except ImportError:
     html_theme = "default"
 
@@ -138,29 +142,33 @@ def fix_circleci(x): return None
 # -- Options for the Sphinx gallery -------------------------------------------
 if has_sphinx_gallery:
     from sphinx_gallery.sorting import ExampleTitleSortKey
+
     extensions += ["sphinx_gallery.gen_gallery"]
     path = Path.cwd()
-    example_dir = path.parent.joinpath('examples')
+    example_dir = path.parent.joinpath("examples")
     sphinx_gallery_conf = {
-        'backreferences_dir': str(path.joinpath('generated', 'modules')),
-        'filename_pattern': '^((?!skip_).)*$',
-        'examples_dirs': example_dir,
-        'within_subsection_order': ExampleTitleSortKey,
-        'gallery_dirs': path.joinpath('generated', 'gallery'),
-        'default_thumb_file': path.joinpath('logo', 'sunpy_icon_128x128.png'),
-        'abort_on_example_error': False,
-        'plot_gallery': True,
-        'doc_module': ('sunpy')
+        "backreferences_dir": str(path.joinpath("generated", "modules")),
+        "filename_pattern": "^((?!skip_).)*$",
+        "examples_dirs": example_dir,
+        "within_subsection_order": ExampleTitleSortKey,
+        "gallery_dirs": path.joinpath("generated", "gallery"),
+        "default_thumb_file": path.joinpath("logo", "sunpy_icon_128x128.png"),
+        "abort_on_example_error": False,
+        "plot_gallery": True,
+        "doc_module": ("sunpy"),
     }
 
 
 def setup(app):
     if not has_sphinx_gallery:
         import warnings
-        warnings.warn('The sphinx_gallery extension is not installed, so the '
-                      'gallery will not be built. You will probably see '
-                      'additional warnings about undefined references due '
-                      'to this.')
+
+        warnings.warn(
+            "The sphinx_gallery extension is not installed, so the "
+            "gallery will not be built. You will probably see "
+            "additional warnings about undefined references due "
+            "to this."
+        )
 
     # The theme conf provides a fix for circle ci redirections
     fix_circleci(app)

docs/index.rst

@@ -2,25 +2,29 @@
 pyflct Documentation
 ********************
 
+.. note::
+    The FLCT C source is licensed under the GNU Lesser General Public License, version 2.1, see ``cextern/COPYRIGHT``.
+
 This is the documentation for pyflct.
 
-pyflct contains routines which can be used to perform Fourier Local Correlation Tracking (FLCT).
-Wrapping a C-based implementation of the FLCT algorithm developed by George H. Fisher and Brian T. Welsch (who we would like to thank for letting us include it).
-`The C source code can be found here <http://cgem.ssl.berkeley.edu/cgi-bin/cgem/FLCT/home>`__.
+pyflct is Python wrapper that allows a user to perform Fourier Local Correlation Tracking (FLCT).
+The C-based implementation of the FLCT algorithm is developed by George H. Fisher and Brian T. Welsch
+and `the source code can be found here <http://cgem.ssl.berkeley.edu/cgi-bin/cgem/FLCT/home>`__.
 
 The following papers are references for the FLCT algorithm:
 
 * `Welsch et al., ApJ 610, 1148, (2004) <https://iopscience.iop.org/article/10.1086/421767>`__
 * `Fisher & Welsch, PASP 383, 373, (2008) <https://arxiv.org/abs/0712.4289>`__
-* `Fisher et al., ApJS, accepted (2020) <https://arxiv.org/abs/0712.4289>`__
+* `Fisher et al., ApJS 248, 1, (2020) <https://iopscience.iop.org/article/10.3847/1538-4365/ab8303>`__
 
-.. note::
-    The FLCT C source is licensed under the GNU Lesser General Public License, version 2.1, see ``cextern/COPYRIGHT``.
+Our Example Gallery provides examples on how to use the Python wrapper.
 
+Contents
+========
 .. toctree::
    :maxdepth: 1
 
    install
-   pyflct
    generated/gallery/index
+   pyflct
    whatsnew/index

docs/install.rst

@@ -2,47 +2,49 @@
 Install
 =======
 
-We recommend the release on the python package index with tools such as pip::
+Linux and Mac OS
+----------------
+
+The simplest way to install this library is through pip::
 
     $ pip install pyflct
 
-Hopefully we will have pre-built binary wheels for Linux nad Mac OS X in the near future.
-Note we do not support Windows the current time.
+This will install the pre-compiled binary wheels for these two platforms.
+
+You can also install it through `Anaconda`_ using the command below used for Windows.
 
-Installation from PyPI may also work on other systems when the FFTW libraries
-are available, but other platforms have not been tested.
+Windows
+-------
 
-Hopefully users of the `conda <https://conda.io/docs/>`__ package manager can install from the `conda-forge <https://conda-forge.org/>`__ channel via::
+We only officially support Windows through `Anaconda`_.
 
     $ conda install -c conda-forge pyflct
 
-in the near future.
+This uses the `conda-forge <https://conda-forge.org/>`__ channel.
 
-Until then you will need to have the FFTW libraries installed on your computer.
+Source Install
+--------------
+
+If you want to install the source only version of pyflct you will need to compile the C extension.
+This means you will need a compiler ("gcc" or "MSVC") and the FFTW library installed.
 
 Linux
------
+^^^^^
 
-Install FFTW from your distrubtion's repositories::
+Install FFTW from your distribution's repositories (some examples)::
 
     $ apt install libfftw3-dev
-
-or::
-
     $ pacman -S fftw3
-
-or::
-
     $ zypper install fftw3-devel
 
-Now install pyfftw from pip::
+Now you install pyfftw from pip::
 
-    $ pip install pyfftw
+    $ pip install --no-binary pyfftw
 
-Mac OS X
---------
+Mac OS
+^^^^^^
 
-Install FFTW from [homebrew](http://brew.sh>)::
+Install FFTW from `homebrew <http://brew.sh>`__::
 
     $ brew install fftw
 
@@ -51,6 +53,51 @@ Set these environmental variables::
     $ export LDFLAGS="-L/usr/local/lib"
     $ export CFLAGS="-I/usr/local/include"
 
-Now install pyfftw from pip::
+Now you install pyfftw from pip::
+
+    $ pip install --no-binary pyfftw
+
+Windows
+^^^^^^^
+
+This is much more involved and we strongly suggest not doing this.
+
+Common Steps
+************
+
+Set up the build environment with MSVC:
+
+* Download `Build Tools for Visual Studio 2019 <https://visualstudio.microsoft.com/downloads/>`__.
+* Install, making sure to check the option "C++ build tools" in the installer.
+
+Anaconda
+********
+
+Set up FFTW::
+
+    $ conda install fftw
+
+Now you install pyfftw from pip::
 
     $ pip install pyfftw
+
+Full source
+***********
+
+Set up FFTW:
+
+* Download ZIP file of `precompiled FFTW Windows DLLs <http://www.fftw.org/install/windows.html>`__ and extract contents to a folder.
+* Open the application "Developer Command Prompt for VS2019", change to the above folder, and run the following commands to create the import libraries (`libfftw3*.lib`)
+
+.. code-block:: console
+
+    lib /def:libfftw3-3.def /machine:x64
+    lib /def:libfftw3f-3.def /machine:x64
+    lib /def:libfftw3l-3.def /machine:x64
+
+* Copy the `libfftw3*.dll` files to somewhere in `%PATH%` (or add the FFTW folder to `%PATH%`).
+  `How to here. <https://stackoverflow.com/a/44272417>`__
+
+* Modify `pyflct/setup_package.py` if not already modified so that the compilation options include the FFTW folder for `include_dirs` and `library_dirs` and the library names for `libraries`.
+
+.. Anaconda: https://www.anaconda.com/products/individual

docs/pyflct.rst

@@ -1,7 +1,10 @@
-===
-API
-===
+=============
+API Reference
+=============
 
-.. automodapi:: pyflct
-  :no-main-docstr:
-  :no-heading:
+This page lists all the functions within pyflct.
+
+
+.. automodapi:: pyflct.flct
+
+.. automodapi:: pyflct.utils