Merge pull request #563 from bmorris3/docs-theme

Docs improvements, new theme

Author: bmorris3

CHANGES.rst

@@ -7,6 +7,8 @@
 - Fix ``Observer`` not having longtitude, latitude, and elevation parameters
   as class attributes. They are now properties calculated from the ``location``.
 
+- Documentation revisions and theme update [#563]
+
 0.8 (2021-01-26)
 ----------------
 

astroplan/plots/sky.py

@@ -1,7 +1,4 @@
 # Licensed under a 3-clause BSD style license - see LICENSE.rst
-from __future__ import (absolute_import, division, print_function,
-                        unicode_literals)
-
 import numpy as np
 import astropy.units as u
 from astropy.time import Time
@@ -120,7 +117,9 @@ def plot_sky(target, observer, time, ax=None, style_kwargs=None,
         if isinstance(plt.gca(), plt.PolarAxes):
             ax = plt.gca()
         else:
-            ax = plt.axes(polar=True)
+            plt.close()
+            fig = plt.gcf()
+            ax = fig.add_subplot(projection='polar')
 
     if style_kwargs is None:
         style_kwargs = {}

astroplan/plots/time_dependent.py

@@ -152,8 +152,11 @@ def plot_airmass(targets, observer, time, ax=None, style_kwargs=None,
     if style_kwargs is None:
         style_kwargs = {}
     style_kwargs = dict(style_kwargs)
-    style_kwargs.setdefault('linewidth', 1.5)
-    style_kwargs.setdefault('fmt', '-')
+
+    if 'lw' not in style_kwargs:
+        style_kwargs.setdefault('linewidth', 1.5)
+    if 'ls' not in style_kwargs and 'linestyle' not in style_kwargs:
+        style_kwargs.setdefault('fmt', '-')
 
     if hasattr(time, 'utcoffset') and use_local_tz:
         tzoffset = time.utcoffset()
@@ -366,9 +369,10 @@ def plot_altitude(targets, observer, time, ax=None, style_kwargs=None,
     if style_kwargs is None:
         style_kwargs = {}
     style_kwargs = dict(style_kwargs)
-    style_kwargs.setdefault('linestyle', '-')
-    style_kwargs.setdefault('linewidth', 1.5)
-    style_kwargs.setdefault('fmt', '-')
+    if 'ls' not in style_kwargs and 'fmt' not in style_kwargs:
+        style_kwargs.setdefault('linestyle', '-')
+    if 'lw' not in style_kwargs:
+        style_kwargs.setdefault('linewidth', 1.5)
 
     # Populate time window if needed.
     time = Time(time)
@@ -591,8 +595,9 @@ def plot_parallactic(target, observer, time, ax=None, style_kwargs=None,
     if style_kwargs is None:
         style_kwargs = {}
     style_kwargs = dict(style_kwargs)
-    style_kwargs.setdefault('linestyle', '-')
     style_kwargs.setdefault('fmt', '-')
+    if 'ls' not in style_kwargs and 'fmt' not in style_kwargs:
+        style_kwargs.setdefault('linestyle', '-')
 
     # Populate time window if needed.
     time = Time(time)

docs/conf.py

@@ -12,12 +12,12 @@
 # See astropy.sphinx.conf for which values are set there.
 
 from configparser import ConfigParser
-import os
+from astroplan import __version__
 import sys
 import datetime
 
 try:
-    from sphinx_astropy.conf.v1 import *  # noqa
+    from sphinx_astropy.conf.v2 import *  # noqa
 except ImportError:
     print('ERROR: the documentation requires the sphinx-astropy package to '
           'be installed')
@@ -34,7 +34,7 @@
 highlight_language = 'python3'
 
 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '1.7'
+# needs_sphinx = '1.7'
 
 # Extend astropy intersphinx_mapping with packages we use here
 intersphinx_mapping['astroquery'] = ('http://astroquery.readthedocs.io/en/latest/', None)
@@ -85,12 +85,6 @@
 # variables set in the global configuration. The variables set in the
 # global configuration are listed below, commented out.
 
-html_theme_options = {
-    'logotext1': 'astro',  # white,  semi-bold
-    'logotext2': 'plan',  # orange, light
-    'logotext3': ':docs'   # white,  light
-    }
-
 # Add any paths that contain custom themes here, relative to this directory.
 # To use a different custom theme, add the directory containing the theme.
 #html_theme_path = []
@@ -179,6 +173,31 @@
 # -- Turn on nitpicky mode for sphinx (to warn about references not found) ----
 nitpicky = True
 
+release = __version__
+dev = "dev" in release
+
+html_copy_source = False
+
+html_theme_options.update(  # noqa: F405
+    {
+        "github_url": "https://github.com/astropy/astroplan",
+        "external_links": [
+            {"name": "astropy docs", "url": "https://docs.astropy.org/en/stable/"},
+        ],
+        "use_edit_page_button": True,
+    }
+)
+
+html_context = {
+    "default_mode": "light",
+    "to_be_indexed": ["stable", "latest"],
+    "is_development": dev,
+    "github_user": "astropy",
+    "github_repo": "astroplan",
+    "github_version": "main",
+    "doc_path": "docs",
+}
+
 #
 # Some warnings are impossible to suppress, and you can list specific references
 # that should be ignored in a nitpick-exceptions file which should be inside

docs/getting_started.rst

@@ -7,7 +7,7 @@ Getting Started
 General Guidelines
 ==================
 
-`astroplan` is based on `Astropy <https://astropy.org>`__ and was built around the creation of Python
+`astroplan` is based on `astropy <https://astropy.org>`__ and was built around the creation of Python
 objects that contain all the information needed to perform certain tasks.  You,
 the user, will create and manipulate these objects to plan your observation. For
 instance, an `~astroplan.Target` object contains information associated with
@@ -57,7 +57,7 @@ Or you can specify your own location parameters::
                    timezone=timezone('US/Hawaii'),
                    description="Subaru Telescope on Maunakea, Hawaii")
 
-`astroplan` makes heavy use of certain `Astropy <https://astropy.org>`__ machinery, including the
+`astroplan` makes heavy use of certain `astropy <https://astropy.org>`__ machinery, including the
 `~astropy.coordinates` objects and transformations and
 `~astropy.units`. Most importantly for basic use of `astroplan` is the
 representation of dates/times as `~astropy.time.Time` objects (note that
@@ -66,10 +66,6 @@ these are in the UTC timezone by default)::
     from astropy.time import Time
     time = Time(['2015-06-16 06:00:00'])
 
-Since `astroplan` objects are Python objects, manipulating them or accessing
-attributes follows Python syntax and conventions.  See Python documentation on
-`objects <https://docs.python.org/2/tutorial/classes.html#instance-objects>`_
-for more information.
 
 Doing More
 ==========

docs/index.rst

@@ -2,13 +2,6 @@
 
 .. _astroplan:
 
-**********************************
-Observation Planning (`astroplan`)
-**********************************
-
-What is astroplan?
-==================
-
 **astroplan** is an open source Python package to help astronomers plan
 observations.
 
@@ -17,7 +10,6 @@ scheduling.  When complete, the goal is to be easy for Python beginners and new
 observers to to pick up, but powerful enough for observatories preparing nightly
 and long-term schedules.
 
-
 Features:
 
 * Calculate rise/set/meridian transit times, alt/az positions for targets at
@@ -26,7 +18,7 @@ Features:
   plots (airmass, parallactic angle, sky maps).
 * Determining observability of sets of targets given an arbitrary set of
   constraints (i.e., altitude, airmass, moon separation/illumination, etc.).
-* `Astropy <https://astropy.org>`__ powered!
+* `astropy <https://astropy.org>`__ powered!
 
 Links
 =====

docs/installation.rst

@@ -10,21 +10,9 @@ Requirements
 ============
 
 **astroplan** works on Linux, Mac OS X and Windows.
-It requires Python 2.7 or 3.5+ (2.6 and 3.2 or earlier are not
-supported, 3.3 and 3.4 may work) as well as the following packages:
-
-* `Numpy`_ (1.10 or later)
-* `Astropy <https://astropy.org>`__ (v1.3 or later)
-* `pytz`_
-
-Optional packages:
-
-* `Matplotlib`_
-* `astroquery`_
-
-For testing:
-
-* `pytest-astropy`_
+It requires Python 3.7+ as well as numpy, astropy, pytz, and six.
+Additional features are available when you install `Matplotlib`_
+and `astroquery`_.
 
 First-time Python users may want to consider an all-in-one Python installation
 package, such as the `Anaconda Python Distribution
@@ -49,29 +37,28 @@ cloning the git repository::
 ...then installing the package with::
 
     cd astroplan
-    python setup.py install
+    pip install .
 
 Testing
 =======
 
 If you want to check that all the tests are running correctly with your Python
-configuration, start up python, and type::
+configuration, run the following from the command line::
 
-    import astroplan
-    astroplan.test()
+    tox -e test
 
 If there are no errors, you are good to go!
 
 .. note::
 	If you want to run the tests that access the internet, you'll need to
-	replace the last line above with ``astroplan.test(remote_data=True)`` and
+	replace the last line above with ``tox -e test -- --remote-data`` and
 	have an active connection to the internet.  Also, if you want the tests
 	that check plotting to work, you need `Matplotlib`_ and `pytest-mpl`_.
 
 More
 ====
 
-astroplan follows `Astropy <https://astropy.org>`__'s guidelines for affiliated packages--installation
-and testing for the two are quite similar! Please see Astropy's
+astroplan follows `astropy <https://astropy.org>`__'s guidelines for affiliated packages--installation
+and testing for the two are quite similar! Please see astropy's
 `installation page <http://astropy.readthedocs.io/en/latest/install.html>`_
 for more information.

setup.cfg

@@ -30,7 +30,7 @@ test =
     pytest-astropy
     pytest-mpl
 docs =
-    sphinx-astropy
+    sphinx-astropy[confv2]
     sphinx-rtd-theme
     matplotlib>=1.4
     astroquery