Grab bag of issues

.pre-commit-config.yaml

@@ -72,10 +72,10 @@ repos:
         args: ['--in-place', '--remove-all-unused-imports', '--remove-unused-variable']
         exclude: ".*(.fits|.fts|.fit|.txt|tca.*|extern.*|.rst|.md|__init__.py|sunpy/extern|docs/conf.py)$"
   - repo: https://github.com/timothycrosley/isort
-    rev: 4.3.21-2
+    rev: 5.1.0
     hooks:
       - id: isort
-        args: ['-sp','setup.cfg','-rc']
+        args: ['--sp','setup.cfg']
         exclude: ".*(.fits|.fts|.fit|.txt|tca.*|extern.*|.rst|.md|cm/__init__.py|sunpy/extern|docs/conf.py)$"
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v2.4.0

CONTRIBUTING.rst

@@ -84,6 +84,16 @@ The main one is the SunPy repository with where all the known `issues`_ with Sun
 Each issue should have a series of labels that provide information about the nature of the issue.
 If you find an issue you'd like to work on, please make sure to add a comment to let people know that you are working on it! This will make it less likely that effort is duplicated.
 
+.. note::
+
+    sunpy is open source, under the BSD-2 license, and by contributing you are stating that you have the right to and agree to, have your work distributed under the terms of this license.
+
+    If you work at a university or research institution, you will need to check if you can contribute code you have written at work.
+    You should start by checking if there is a Open Source Software Policy (e.g., `Standford's policy <https://otl.stanford.edu/open-source-stanford>`__) for your work place.
+    If not, `OSS-Watch <http://oss-watch.ac.uk/resources/contributing>`__ summaries what you will need to check and who to ask, however this is from a UK point of view.
+    `Standford's guidance <https://otl.stanford.edu/sites/g/files/sbiybj10286/f/otlcopyrightguide.pdf>`__ for example allows someone to contribute and open source their code.
+    If you are unsure if your university or institution allows you to contribute under the BSD-2 license, you should contact the relevant department or administrator that deals with copyright.
+
 If you are unsure where to start we suggest the `Good First Issue label`_.
 These are issues that have been deemed a good way to be eased into SunPy and are achievable with little understanding of the SunPy codebase.
 Please be aware that this does not mean the issue is "easy", just that you do not need to be aware of the underlying structure of SunPy.

docs/conf.py

@@ -39,12 +39,12 @@
 
 # -- Non stdlib imports --------------------------------------------------------
 
-import ruamel.yaml as yaml
-from sphinx_gallery.sorting import ExplicitOrder
-from sphinx_gallery.sorting import ExampleTitleSortKey
+import ruamel.yaml as yaml  # NOQA
+from sphinx_gallery.sorting import ExplicitOrder  # NOQA
+from sphinx_gallery.sorting import ExampleTitleSortKey  # NOQA
 
-import sunpy
-from sunpy import __version__
+import sunpy  # NOQA
+from sunpy import __version__  # NOQA
 
 # -- Project information -------------------------------------------------------
 
@@ -62,7 +62,7 @@
 # in the CI, especially RTD.
 ori_level = sunpy.log.level
 sunpy.log.setLevel("DEBUG")
-import sunpy.data.sample  # isort:skip
+import sunpy.data.sample  # NOQA
 sunpy.log.setLevel(ori_level)
 
 # For the linkcheck
@@ -85,29 +85,28 @@
 
 # Suppress warnings about overriding directives as we overload some of the
 # doctest extensions.
-suppress_warnings = ['app.add_directive',]
+suppress_warnings = ['app.add_directive', ]
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'matplotlib.sphinxext.plot_directive',
+    'sphinx_automodapi.automodapi',
+    'sphinx_automodapi.smart_resolver',
+    'sphinx_gallery.gen_gallery',
     'sphinx.ext.autodoc',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.todo',
     'sphinx.ext.coverage',
-    'sphinx.ext.inheritance_diagram',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.napoleon',
     'sphinx.ext.doctest',
+    'sphinx.ext.inheritance_diagram',
+    'sphinx.ext.intersphinx',
     'sphinx.ext.mathjax',
-    'sphinx_automodapi.automodapi',
-    'sphinx_automodapi.smart_resolver',
-    'sphinx_gallery.gen_gallery',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
+    'sunpy.util.sphinx.changelog',
     'sunpy.util.sphinx.doctest',
-    'matplotlib.sphinxext.plot_directive',
-    'sunpy.util.sphinx.minigallery',
     'sunpy.util.sphinx.generate',
-    'sunpy.util.sphinx.changelog',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -161,7 +160,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 
-from sunpy_sphinx_theme.conf import *
+from sunpy_sphinx_theme.conf import *  # NOQA
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -202,9 +201,9 @@
     'gallery_dirs': os.path.join('generated', 'gallery'),
     'default_thumb_file': os.path.join('logo', 'sunpy_icon_128x128.png'),
     'abort_on_example_error': False,
-    'plot_gallery': True,
+    'plot_gallery': 'True',
     'remove_config_comments': True,
-    'doc_module': ('sunpy')
+    'doc_module': ('sunpy'),
 }
 
 # -- Stability Page ------------------------------------------------------------
@@ -216,6 +215,7 @@
     'sunpy_modules': sunpy_modules
 }
 
+
 def rstjinja(app, docname, source):
     """
     Render our pages as a jinja template for fancy templating goodness.
@@ -232,7 +232,14 @@ def rstjinja(app, docname, source):
 
 # -- Sphinx setup --------------------------------------------------------------
 
+
 def setup(app):
+    # If SunpyDeprecationWarning is raised, we want it to error
+    import os
+    import warnings
+    from sunpy.util.exceptions import SunpyDeprecationWarning
+    warnings.simplefilter("error", SunpyDeprecationWarning)
+    os.environ["PYTHONWARNINGS"] = "error::sunpy.util.exceptions.SunpyDeprecationWarning"
     # Generate the stability page
     app.connect("source-read", rstjinja)
 

docs/dev_guide/code_standards.rst

@@ -52,24 +52,37 @@ Coding Style/Conventions
 Formatting
 ==========
 
-We enforce a minimum level of code style and we have tools that will automate this step for you.
+We enforce a minimum level of code style with our continuous intergration (the name is ``sunpy.sunpy (python_codestyle [linux]``).
+This runs a tool called `https://pre-commit.com/ <https://pre-commit.com/>`__.
 
-First step is to install pre-commit::
+Using "tox" allows you to run these tools without having to setup anything within your own Python virtual environment::
+
+    $ tox -e codestyle
+
+If you want to setup the pre-commit locally, you can do the following::
 
     $ pip install pre-commit
 
 Now you can do::
 
     $ pre-commit run --all-files
 
-which will run the tools on all the files and make the necessary adjustments.
-This will show up as new changes that you can review before you commit your work.
+which will run the tools on all files in the sunpy git repository.
+The pre-commit tools can change some of the files, in other cases it will report problems but will require manual correction.
+If the pre-commit tool changes any files, they will show up as new changes that will need to be committed.
 
-The other option is to::
+Instead of running the pre-commit command each time you can install the git hook::
 
     $ pre-commit install
 
 which installs a command to `.git/hooks/pre-commit` which will run these tools at the time you do ``git commit`` and means you don't have to run the first command each time.
+We only suggest doing the install step if you are comfortable with git and the pre-commit tool.
+
+The settings and tools we use for the pre-commit can be found in the file `.pre-commit-config.yaml` at the root of the sunpy git repository.
+Some of the checks are:
+* Check (but will not fix) for various PEP8 issues with flake8.
+* Sort all imports in any Python files with isort.
+* Remove any unused variables or imports with autoflake.
 
 Documentation and Testing
 =========================

docs/dev_guide/documentation.rst

@@ -10,25 +10,79 @@ Overview
 All code must be documented and we follow these style conventions described here:
 
 * `numpydoc <https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard>`_
-* `astropy <https://docs.astropy.org/en/latest/development/docrules.html>`_
 
-We recommend familiarizing yourself with these references.
+We recommend familiarizing yourself with this style.
 
-Differences
------------
+Referring to other code
+-----------------------
 
-The current differences we have are as follows:
+To link to other methods, classes, or modules in sunpy you have to use backticks, for example:
 
-We backtick each type in the documentation strings so that they are interlinked by our documentation builder:
+.. code-block:: rst
 
-.. code-block:: python
+    `sunpy.io.file_tools.read_file`
 
-    """
-    Parameters
-    ----------
-    x : `type`
-       Description of parameter x.
-    """
+generates a link like this: `sunpy.io.file_tools.read_file`.
+
+We use the sphinx setting ``default_role = 'obj'`` so that you don't have to use qualifiers like ``:class:``, ``:func:``, ``:meth:`` and the like.
+
+Often, you don't want to show the full package and module name.
+As long as the target is unambiguous you can simply leave them out:
+
+.. code-block:: rst
+
+    `.read_file`
+
+and the link still works: `.read_file`.
+
+If there are multiple code elements with the same name (e.g. ``peek()`` is a method in multiple classes), you'll have to extend the definition:
+
+.. code-block:: rst
+
+    `GenericMap.peek` or `CompositeMap.peek`
+
+These will show up as `GenericMap.peek` or `CompositeMap.peek`.
+To still show only the last segment you can add a tilde as prefix:
+
+.. code-block:: rst
+
+    `~.GenericMap.peek` or `~.CompositeMap.peek`
+
+will render as `~.GenericMap.peek` or `~.CompositeMap.peek`.
+
+Other packages can also be linked via
+`intersphinx <http://www.sphinx-doc.org/en/master/ext/intersphinx.html>`_:
+
+.. code-block:: rst
+
+    `numpy.max`
+
+will return this link: `numpy.max`.
+This works for Python, Numpy and Astropy (full list is in :file:`docs/conf.py`).
+If external linking fails, you can check the full list of referenceable objects with the following
+commands::
+
+    $ python -m sphinx.ext.intersphinx 'https://docs.python.org/3/objects.inv'
+
+If you want to link to a method or function you can add:
+
+.. code-block:: rst
+
+    :func:`numpy.mean`
+
+which will render a link and extra brackets :func:`numpy.mean`.
+If you decide to use ``:meth:`` instead this will also render extra brackets but will not link in this case.
+This is because "numpy.mean" is a function.
+
+If you link to a method of a class, it will work.
+
+.. code-block:: rst
+
+    :meth:`numpy.ndarray.mean`
+
+:meth:`numpy.ndarray.mean` but ``:func:`` will not.
+
+Never add ``:class:`` this will break the linking.
 
 SunPy-Specific Rules
 --------------------
@@ -44,6 +98,7 @@ SunPy-Specific Rules
 
 Documenting Data Sources
 ----------------------------
+
 Subclasses of `~sunpy.map.GenericMap` or `~sunpy.timeseries.TimeSeries` must provide a detailed docstring providing an overview of the data source that the object represents.
 In order to maintain consistency and completeness, the following information must be provided by a data source docstring, if available, and preferably in the following order:
 
@@ -67,7 +122,7 @@ In addition, a reference section must be provided with links to the following re
 * information to interpret metadata keywords such as FITS header reference
 * the data archive
 
-An example docstring can be found in the :ref:`Writing a new Instrument Map Class guide<new_maps_ts_etc>`.
+An example docstring can be found in the :ref:`Writing a new Instrument Map Class guide <new_maps_ts_etc>`.
 
 Sphinx
 ======
@@ -94,7 +149,7 @@ Sphinx builds documentation iteratively, only adding things that have changed.
 
 If you want to build the documentation without building the gallery, i.e. to reduce build times while working on other sections of the documentation you can run::
 
-    $ tox -e build_docs -- -D plot_gallery=0
+    $ tox -e build_docs -- -D plot_gallery=False
 
 If you'd like to start from scratch (i.e., remove the tox cache) then run::