Merge pull request #48 from pysat/doc/2021_apr

DOC: documentation updates

.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Documentation Check
+
+on: [push, pull_request]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [3.9]
+
+    name: Documentation tests
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r test_requirements.txt
+        pip install -r requirements.txt
+
+    - name: Set up pysat
+      run: |
+        mkdir pysatData
+        python -c "import pysat; pysat.params['data_dirs'] = './pysatData'"
+
+    - name: Check documentation build
+      run: sphinx-build -E -b html docs dist/docs
+
+    - name: Check documentation links
+      run: sphinx-build -b linkcheck docs dist/docs
+
+    - name: Load .zenodo.json to check for errors
+      run: python -c "import json; json.loads(open('.zenodo.json').read())"

.zenodo.json

@@ -0,0 +1,27 @@
+{
+    "creators": [
+      {
+        "affiliation": "Goddard Space Flight Center",
+        "name": "Klenzing, Jeffrey",
+        "orcid": "0000-0001-8321-6074"
+      },
+      {
+        "affiliation": "The University of Texas at Dallas",
+        "name": "Stoneback, Russell",
+        "orcid": "0000-0001-7216-4336"
+      },
+      {
+        "affiliation": "U.S. Naval Research Laboratory",
+        "name": "Burrell, Angeline G.",
+        "orcid": "0000-0001-8875-9326"
+      },
+      {
+        "affiliation": "The University of Texas at Dallas",
+        "name": "Depew, Matthew"
+      },
+      {
+        "name": "Spence, Carey",
+        "orcid": "0000-0001-8340-5625"
+      }
+    ]
+}

CONTRIBUTING.md

@@ -48,9 +48,9 @@ To set up `pysatMissions` for local development:
     git checkout -b name-of-your-bugfix-or-feature
 
    Now you can make your changes locally. Tests for new instruments are
-   performed automatically.  Tests for custom functions should be added to the
-   appropriately named file in ``pysatMissions/tests``.  For example, the averaging routines in avg.py are tested in ``pysatMissions/tests/test_avg.py``.  If no
-   test file exists, then you should create one.  This testing uses pytest, which
+   performed automatically.  Tests for custom functions should be added to
+   the appropriately named file in ``pysatMissions/tests``.  If no test
+   file exists, then you should create one.  This testing uses pytest, which
    will run tests on any python file in the test directory that starts with
    ``test_``.
 

README.md

@@ -50,14 +50,7 @@ python setup.py install
 
 Note: pre-1.0.0 version
 ------------------
-pysatMissions is currently in an initial development phase.  Much of the API is being built off of the upcoming pysat 3.0.0 software in order to streamline the usage and test coverage.  This version of pysat is planned for release later this year.  Currently, you can access the develop version of this through github:
-```
-git clone https://github.com/pysat/pysat.git
-cd pysat
-git checkout develop-3
-python setup.py install
-```
-It should be noted that this is a working branch and is subject to change.
+pysatNASA is currently in an initial development phase and requires pysat 3.0.0.  
 
 # Using with pysat
 
@@ -69,3 +62,12 @@ from pysatMissions.instruments import pysat_ephem
 
 simInst = pysat.Instrument(inst_module=pysat_ephem)
 ```
+Another way to use the instruments in an external repository is to register the instruments.  This only needs to be done the first time you load an instrument.  Afterward, pysat will identify them using the `platform` and `name` keywords.
+
+```
+import pysat
+import pysatMissions
+
+pysat.utils.registry.register_by_module(pysatMissions.instruments)
+simInst = pysat.Instrument('pysat', 'ephem')
+```

docs/citing.rst

@@ -1,46 +1,31 @@
-Citations in the pysat ecosystem
-================================
-
-When referring to this software package, please cite the original paper by Stoneback et al [2018] https://doi.org/10.1029/2018JA025297 as well as the package https://doi.org/10.5281/zenodo.3475498. Note that this doi will always point to the latest version of the code.  A list of dois for all versions can be found at the [zenodo page](https://zenodo.org/record/3475499).
-
-Example for citation in BibTex for a generalized version:
-
-.. code::
-
-  @misc{pysatMissions,
-    author       = {Stoneback, R.A. and
-                    Klenzing, J.H. and
-                    Burrell, A.G. and
-                    Depew, M. and
-                    Spence, C.},
-    title        = {Pysat Mission Planning Toolkit (pysatMissions) vX.Y.Z},
-    month        = oct,
-    year         = 2019,
-    doi          = {10.5281/zenodo.3475499},
-    url          = {https://doi.org/10.5281/zenodo.3475499}
+Citation Guidelines
+===================
+
+When publishing work that uses pysatMissions, please cite the package and
+any package it depends on that plays an important role in your analysis.
+Specifying which version of pysatMissions used will also improve the
+reproducibility of your presented results.
+
+pysatMissions
+-------------
+
+* Jeff Klenzing, Russell Stoneback, Angeline Burrell, Matthew Depew,
+  & Carey Spence. (2020, July 29). pysat/pysatMissions: Version 0.2.1
+  (Version v0.2.1). Zenodo. http://doi.org/10.5281/zenodo.3966508
+
+.. code-block:: latex
+
+  @software{pysatMissions,
+  author       = {Klenzing, Jeff and
+                  Stoneback, Russell and
+                  Burrell, Angeline and
+                  Depew, Matthew and
+                  Spence, Carey},
+  title        = {pysat/pysatMissions: Version 0.2.1},
+  month        = jul,
+  year         = 2020,
+  publisher    = {Zenodo},
+  version      = {v0.2.1},
+  doi          = {10.5281/zenodo.3966508},
+  url          = {https://doi.org/10.5281/zenodo.3966508}
   }
-
-Citing the publication:
-
-.. code::
-
-  @article{Stoneback2018,
-    author    = {Stoneback, R. A. and
-                 Burrell, A. G. and
-                 Klenzing, J. and
-                 Depew, M. D.},
-    doi       = {10.1029/2018JA025297},
-    issn      = {21699402},
-    journal   = {Journal of Geophysical Research: Space Physics},
-    number    = {6},
-    pages     = {5271--5283},
-    title     = {{PYSAT: Python Satellite Data Analysis Toolkit}},
-    volume    = {123},
-    year      = {2018}
-  }
-
-To aid in scientific reproducibility, please include the version number in publications that use this code.  This can be found by invoking
-
-.. code::
-
-  pysatMissions.__version__

docs/conf.py

@@ -12,16 +12,21 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+import json
 import os
 import sys
 sys.path.insert(0, os.path.abspath('..'))
 from pysatMissions import __version__
 
 # -- Project information -----------------------------------------------------
 
+zenodo = json.loads(open('../.zenodo.json').read())
+
 project = 'pysatMissions'
-copyright = '2020, Russell Stoneback'
-author = 'Jeff Klenzing \\and Russell Stoneback \\and Angeline Burrell'
+author = ', '.join([x['name'] for x in zenodo['creators']])
+copyright = ', '.join(['2021', author])
+title = 'pysatMissions Documentation'
+description = 'Tools for generating simulated instruments in pysat.'
 
 # The short X.Y version
 version = __version__[::-1].partition('.')[2][::-1]
@@ -38,16 +43,16 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.doctest',
-    'sphinx.ext.todo',
-    'sphinx.ext.imgmath',
-    'sphinx.ext.autosummary',
-    'sphinx.ext.napoleon',
-    'numpydoc',
-    'IPython.sphinxext.ipython_console_highlighting'
-]
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.intersphinx',
+              'sphinx.ext.doctest',
+              'sphinx.ext.todo',
+              'sphinx.ext.imgmath',
+              'sphinx.ext.autosummary',
+              'sphinx.ext.napoleon',
+              'numpydoc',
+              'IPython.sphinxext.ipython_console_highlighting',
+              'm2r2']
 
 numpydoc_show_class_members = False
 
@@ -84,7 +89,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -138,8 +143,8 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'pysatMissions.tex', 'pysatMissions Documentation',
-     'Jeff Klenzing', 'manual'),
+    (master_doc, '{:s}.tex'.format(project), title,
+     author, 'manual'),
 ]
 
 
@@ -148,7 +153,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'pysatMissions', 'pysatMissions Documentation',
+    (master_doc, project, title,
      [author], 1)
 ]
 
@@ -159,9 +164,9 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'pysatMissions', 'pysatMissions Documentation',
-     author, 'pysatMissions', 'One line description of project.',
-     'Miscellaneous'),
+    (master_doc, project, title,
+     author, project, description,
+     'Space Physics'),
 ]
 
 

docs/develop_guide.rst

@@ -0,0 +1,6 @@
+Guide for Developers
+====================
+
+.. toctree::
+   develop_guide/code_of_conduct.rst
+   develop_guide/contributing.rst

docs/develop_guide/code_of_conduct.rst

@@ -0,0 +1 @@
+.. mdinclude:: ../../CODE_OF_CONDUCT.md

docs/develop_guide/contributing.rst

@@ -0,0 +1 @@
+.. mdinclude:: ../../CONTRIBUTING.md

docs/history.rst

@@ -0,0 +1 @@
+.. mdinclude:: ../CHANGELOG.md

docs/index.rst

@@ -1,14 +1,20 @@
 .. pysatMissions documentation main file
 
-Welcome to pysatMissions's documentation!
-=========================================
+Welcome to the pysatMissions documentation!
+===========================================
+
+This documentation describes the pysatMissions module, which contains
+routines to generate simualted instruments using Two-Line Elements (TLEs),
+as well as apply geomagnetic field models to existing pysat instruments.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: -1
 
    introduction.rst
    installation.rst
-   tutorial.rst
-   contributing.rst
    citing.rst
+   supported_instruments.rst
+   tutorial.rst
    references.rst
+   develop_guide.rst
+   history.rst