commit updated doc build and changes in docstrings

README.md

@@ -1,5 +1,3 @@
-# NasaPy
-
 [![Documentation Status](https://readthedocs.org/projects/nasapy/badge/?version=latest)](https://nasapy.readthedocs.io/en/latest/?badge=latest)
 [![Build Status](https://travis-ci.org/aschleg/nasapy.svg?branch=master)](https://travis-ci.org/aschleg/nasapy)
 [![Build status](https://ci.appveyor.com/api/projects/status/h36pef9i0o1rjosy?svg=true)](https://ci.appveyor.com/project/aschleg/nasapy)
@@ -9,11 +7,13 @@
 [![https://pypi.org/project/nasapy/](https://img.shields.io/badge/pypi%20version-0.1.0-blue.svg)](https://pypi.org/project/nasapy/)
 [![https://pypi.org/project/nasapy/](https://img.shields.io/badge/python-3.4%2C%203.5%2C%203.6%2C%203.7-blue.svg)](https://pypi.org/project/nasapy/)
 
+# NasaPy
+
 Python wrapper for the [nasa.gov API](https://api.nasa.gov/).
 
 ## Installation
 
-`nasapy` is most easily installed using `pip`
+`nasapy` is most easily installed using `pip`.
 
 ```bash
 pip install nasapy

docs/build/html/_sources/api.rst.txt

@@ -11,7 +11,7 @@ API Reference
 
     Class object containing the methods for interacting with NASA API endpoints that require an API key.
 
-    :param key: The generated API key received from the NASA API. Registering for an API key can be done on the `NASA API webpage <https://api.nasa.gov/>`_. If :code:`None`, a 'DEMO_KEY' with a much more restricted access limited is used.
+    :param key: The generated API key received from the NASA API. Registering for an API key can be done on the `NASA API webpage <https://api.nasa.gov/>`_. If :code:`None`, a 'DEMO_KEY' with a much more restricted access limit is used.
 
 Astronomy Picture of the Day
 ++++++++++++++++++++++++++++
@@ -473,6 +473,26 @@ and `Center for Near-Earth Object Studies <https://cneos.jpl.nasa.gov/>`_ APIs.
         # Get close-approach data for asteroid 433 Eros within 0.2AU from the years 1900 to 2100.
         >>> nasapy.close_approach(des='433', date_min='1900-01-01', date_max='2100-01-01', dist_max=0.2)
 
+    Each close-approach record is a list containing the following fields in the corresponding order:
+
+    * des - primary designation of the asteroid or comet (e.g., 443, 2000 SG344)
+    * orbit_id - orbit ID
+    * jd - time of close-approach (JD Ephemeris Time)
+    * cd - time of close-approeach (formatted calendar date/time)
+    * dist - nominal approach distance (au)
+    * dist_min - minimum (3-sigma) approach distance (au)
+    * dist_max - maximum (3-sigma) approach distance (au)
+    * v_rel - velocity relative to the approach body at close approach (km/s)
+    * v_inf - velocity relative to a massless body (km/s)
+    * t_sigma_f - 3-sigma uncertainty in the time of close-approach (formatted in days, hours, and minutes; days are not included if zero; example “13:02” is 13 hours 2 minutes; example “2_09:08” is 2 days 9 hours 8 minutes)
+    * body - name of the close-approach body (e.g., Earth)
+
+      - only output if the body query parameters is set to ALL
+    * h - absolute magnitude H (mag)
+    * fullname - formatted full-name/designation of the asteroid or comet
+
+      - optional - only output if requested with the appropriate query flag
+      - formatted with leading spaces for column alignment in monospaced font tables
 
 .. method:: fireballs([date_min=None][, date_max=None][, energy_min=None][, energy_max=None][, impact_e_min=None][, impact_e_max=None][, vel_min=None][, vel_max=None][, alt_min=None][, alt_max=None][, req_loc=False][, req_alt=False][, req_vel=False][, req_vel_comp=False][, vel_comp=False][, sort='date'][, limit=None])
 

docs/build/html/_sources/index.rst.txt

@@ -1,5 +1,8 @@
 
+Nasapy Documentation
+====================
 
+:code:`nasapy` is a Python wrapper for the `nasa.gov API <https://api.nasa.gov/>`_.
 
 Contents
 ========
@@ -8,4 +11,213 @@ Contents
    :maxdepth: 1
 
    api.rst
-   versions.rst
+   versions.rst
+
+Installation
+============
+
+:code:`nasapy` is most easily installed using :code:`pip`.
+
+.. code-block:: console
+
+    pip install nasapy
+
+The library can also be cloned or downloaded into a location of your choosing and then installed using the `setup.py`
+file per the following:
+
+.. code-block:: console
+
+    git clone git@github.com:aschleg/nasapy.git
+    cd nasapy
+    python setup.py install
+
+Examples and Usage
+==================
+
+Although not strictly required to begin interacting with the NASA API, it is recommended to sign up
+to receive an `API access key <https://api.nasa.gov/>`_ that has a significantly higher usage limit available compared
+to the demo key option. Many methods do not require an API key, but for those that do, it is typically a good option to
+use a provided API key rather than the demo key. Using a received API key allows for 1,000 requests per hour, while the
+demo key has 30 requests limit per hour and 50 requests per day.
+
+Authentication
+--------------
+
+Assuming an API key was received after signing up, authentication to the NASA API happens when initializing the
+:code:`Nasa` class.
+
+.. code-block:: python
+
+    nasa = Nasa(key=key)
+
+If using a demo key, the initialization does not require any parameters to be passed.
+
+.. code-block:: python
+
+    nasa = Nasa()
+
+Remaining Requests Available
+----------------------------
+
+The :code:`limit_remaining` attribute of the initialized :code:`Nasa` class allows one to see the number of available
+requests remaining.
+
+.. code-block:: python
+
+    nasa.limit_remaining
+
+Examples
+--------
+
+The following are some quick examples to get started.
+
+Astronomy Picture of the Day
+++++++++++++++++++++++++++++
+
+.. code-block:: python
+
+    # Return today's picture of the day
+    nasa.picture_of_the_day()
+    # Return a previous date's picture of the day with the high-definition URL included.
+    nasa.picture_of_the_day('2019-01-01', hd=True)
+
+Mars Weather
+++++++++++++
+
+.. code-block:: python
+
+    # Return the most recent data for the previous seven Sols (Martian Days)
+    nasa.mars_weather()
+
+Asteroid Feed
++++++++++++++
+
+.. code-block:: python
+
+    # Get asteroids approaching Earth at the beginning of 2019.
+    nasa.asteroid_feed(start_date='2019-01-01')
+
+Get Asteroid Data
++++++++++++++++++
+
+.. code-block:: python
+
+    # Get entire asteroid data set.
+    nasa.get_asteroids()
+    # Get asteroid with ID 3542519
+    nasa.get_asteroids(asteroid_id=3542519)
+
+DONKI (Space Weather Database of Notifications, Knowledge and Information)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. code-block:: python
+
+    # Coronal Mass Ejection Event Data
+
+    # View data from coronal mass ejection events from the last thirty days
+    nasa.coronal_mass_ejection()
+    # View all CME events from the beginning of 2019.
+    nasa.coronal_mass_ejection(start_date='2019-01-01', end_date=datetime.datetime.today())
+
+    # Geomagnetic Storm Event Data
+
+    # Get geomagnetic storm events from the last thirty days.
+    nasa.geomagnetic_storm()
+
+    # Solar Flare Event Data
+
+    # Get solar flare events from May of 2019
+    nasa.solar_flare(start_date='2019-05-01', end_date='2019-05-31')
+
+    # Solar Energetic Particle Data
+
+    # Get data from April 2017
+    nasa.solar_energetic_particle(start_date='2017-04-01', end_date='2017-04-30')
+
+    # Magnetopause Crossing Data
+
+    # Get data on magnetopause crossing events from 2018 to the current date.
+    nasa.magnetopause_crossing(start_date='2018-01-01')
+
+    # Radiation Belt Enhancement Data
+
+    # Get data on radiation belt enhancement events from the last 30 days.
+    nasa.radiation_belt_enhancement()
+
+    # Hight Speed Stream Data
+
+    # Get data on hight speed stream events from the beginning of September 2019.
+    nasa.hight_speed_stream()
+
+    # WSA Enlil-Simulation Data
+
+    # Get data from the first simulation performed in 2019.
+    wsa = n.wsa_enlil_simulation(start_date='2019-01-01')
+    wsa[0]
+
+EPIC (DSCOVR's Earth Polychromatic Imaging Camera)
+++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. code-block:: python
+
+    # Get EPIC data from the beginning of 2019.
+    e = nasa.epic(date='2019-01-01')
+    # Print the first result
+    e[0]
+
+Landsat Images for a given Latitude-Longitude
++++++++++++++++++++++++++++++++++++++++++++++
+
+.. code-block:: python
+
+    # Get imagery at latitude 1.5, longitude 100.75 and include the computed cloud score calculation.
+    nasa.earth_imagery(lon=100.75, lat=1.5, cloud_score=True)
+
+    # Get assets available beginning from 2014-02-01 at lat-lon 100.75, 1.5
+    nasa.earth_assets(lat=100.75, lon=1.5, begin_date='2014-02-01')
+
+Available Image data collected by the Mars rovers Curiosity, Discovery and Spirit.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. code-block:: python
+
+    # Return image data collected on Curiosity's 1000th sol.
+    nasa.mars_rover(sol=1000)
+
+Access GeneLab and Other Bioinformatics Databases
++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. code-block:: python
+
+    # Find Gene studies in the cgene database related to 'mouse liver'
+    n.genelab_search(term='mouse liver')
+
+CelesTrak Two-Line Element Set Records
+++++++++++++++++++++++++++++++++++++++
+
+.. code-block:: python
+
+    # Retrieve available data for a specific satellite ID.
+    tle(satellite_number=43553)
+
+Search for Available Imagery and Audio from the images.nasa.gov API
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. code-block:: python
+
+    # Search for media related to 'apollo 11' with 'moon landing' in the description of the items.
+    r = media_search(query='apollo 11', description='moon landing')
+    # Print the first returned media item from the resulting collection.
+    r['items'][0]
+
+Getting the Julian and Modified Julian Date
++++++++++++++++++++++++++++++++++++++++++++
+
+.. code-block:: python
+
+    # Return the modified Julian Date for the current time.
+    julian_date()
+    # Return the non-modified Julian Date for the current time.
+    julian_date(modified=False)
+    # Get the modified Julian Date for 2019-01-01 at midnight.
+    julian_date(year=2019)

docs/build/html/api.html

@@ -38,7 +38,7 @@
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
     <link rel="next" title="Version History" href="versions.html" />
-    <link rel="prev" title="Contents" href="index.html" /> 
+    <link rel="prev" title="Nasapy Documentation" href="index.html" /> 
 </head>
 
 <body class="wy-body-for-nav">
@@ -183,7 +183,7 @@ <h2><a class="reference internal" href="#Nasa" title="Nasa"><code class="xref py
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>key</strong> – The generated API key received from the NASA API. Registering for an API key can be done on the <a class="reference external" href="https://api.nasa.gov/">NASA API webpage</a>. If <code class="code docutils literal notranslate"><span class="pre">None</span></code>, a ‘DEMO_KEY’ with a much more restricted access limited is used.</td>
+<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>key</strong> – The generated API key received from the NASA API. Registering for an API key can be done on the <a class="reference external" href="https://api.nasa.gov/">NASA API webpage</a>. If <code class="code docutils literal notranslate"><span class="pre">None</span></code>, a ‘DEMO_KEY’ with a much more restricted access limit is used.</td>
 </tr>
 </tbody>
 </table>
@@ -923,6 +923,29 @@ <h3>Solar System Dynamics (SSD) and Center for Near-Earth Object Studies (CNEOS)
 <span class="o">&gt;&gt;&gt;</span> <span class="n">nasapy</span><span class="o">.</span><span class="n">close_approach</span><span class="p">(</span><span class="n">des</span><span class="o">=</span><span class="s1">&#39;433&#39;</span><span class="p">,</span> <span class="n">date_min</span><span class="o">=</span><span class="s1">&#39;1900-01-01&#39;</span><span class="p">,</span> <span class="n">date_max</span><span class="o">=</span><span class="s1">&#39;2100-01-01&#39;</span><span class="p">,</span> <span class="n">dist_max</span><span class="o">=</span><span class="mf">0.2</span><span class="p">)</span>
 </pre></div>
 </div>
+<p>Each close-approach record is a list containing the following fields in the corresponding order:</p>
+<ul class="simple">
+<li>des - primary designation of the asteroid or comet (e.g., 443, 2000 SG344)</li>
+<li>orbit_id - orbit ID</li>
+<li>jd - time of close-approach (JD Ephemeris Time)</li>
+<li>cd - time of close-approeach (formatted calendar date/time)</li>
+<li>dist - nominal approach distance (au)</li>
+<li>dist_min - minimum (3-sigma) approach distance (au)</li>
+<li>dist_max - maximum (3-sigma) approach distance (au)</li>
+<li>v_rel - velocity relative to the approach body at close approach (km/s)</li>
+<li>v_inf - velocity relative to a massless body (km/s)</li>
+<li>t_sigma_f - 3-sigma uncertainty in the time of close-approach (formatted in days, hours, and minutes; days are not included if zero; example “13:02” is 13 hours 2 minutes; example “2_09:08” is 2 days 9 hours 8 minutes)</li>
+<li>body - name of the close-approach body (e.g., Earth)<ul>
+<li>only output if the body query parameters is set to ALL</li>
+</ul>
+</li>
+<li>h - absolute magnitude H (mag)</li>
+<li>fullname - formatted full-name/designation of the asteroid or comet<ul>
+<li>optional - only output if requested with the appropriate query flag</li>
+<li>formatted with leading spaces for column alignment in monospaced font tables</li>
+</ul>
+</li>
+</ul>
 </dd></dl>
 
 <dl class="method">
@@ -1177,7 +1200,7 @@ <h3>Other Methods<a class="headerlink" href="#other-methods" title="Permalink to
         <a href="versions.html" class="btn btn-neutral float-right" title="Version History" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
 
 
-        <a href="index.html" class="btn btn-neutral float-left" title="Contents" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
+        <a href="index.html" class="btn btn-neutral float-left" title="Nasapy Documentation" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
 
     </div>