Merge pull request #108 from pysat/sty/rtd

DOC/STY: formatting contributing page in docs

CHANGELOG.md

@@ -14,6 +14,7 @@ This project adheres to [Semantic Versioning](https://semver.org/).
   * Updated NEP29 compliance in Github Actions
   * Limit versions of hacking for improved pip compliance
   * Update instrument template standards
+  * Updated documentation style
   * Removed cap on cdflib
 
 

CONTRIBUTING.md

@@ -1,36 +1,46 @@
 Contributing
 ============
 
-Bug reports, feature suggestions and other contributions are greatly
+Bug reports, feature suggestions, and other contributions are greatly
 appreciated!  pysat is a community-driven project and welcomes both feedback and
 contributions.
 
+Come join us on Slack! An invitation to the pysat workspace is available
+in the 'About' section of the
+[pysat GitHub Repository.](https://github.com/pysat/pysat) Development meetings
+are generally held fortnightly.
+
 Short version
 -------------
 
-* Submit bug reports and feature requests at `GitHub <https://github.com/pysat/pysatNASA/issues>`_
+* Submit bug reports and feature requests at [GitHub](https://github.com/pysat/pysatNASA/issues)
+
 * Make pull requests to the ``develop`` branch
 
 Bug reports
 -----------
 
-When `reporting a bug <https://github.com/pysat/pysatNASA/issues>`_ please
+When [reporting a bug](https://github.com/pysat/pysatNASA/issues) please
 include:
 
 * Your operating system name and version
+
 * Any details about your local setup that might be helpful in troubleshooting
+
 * Detailed steps to reproduce the bug
 
 Feature requests and feedback
 -----------------------------
 
 The best way to send feedback is to file an issue at
-`GitHub <https://github.com/pysat/pysatNASA/issues>`_.
+[GitHub](https://github.com/pysat/pysatNASA/issues).
 
 If you are proposing a feature:
 
 * Explain in detail how it would work.
+
 * Keep the scope as narrow as possible, to make it easier to implement.
+
 * Remember that this is a volunteer-driven project, and that code contributions
   are welcome :)
 
@@ -39,19 +49,24 @@ Development
 
 To set up `pysatNASA` for local development:
 
-1. `Fork pysatNASA on GitHub <https://github.com/pysat/pysatNASA/fork>`_.
-2. Clone your fork locally::
+1. [Fork pysatNASA on GitHub](https://github.com/pysat/pysatNASA/fork).
+
+2. Clone your fork locally:
 
+  ```
     git clone git@github.com:your_name_here/pysatNASA.git
+  ```
 
-3. Create a branch for local development::
+3. Create a branch 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.  See discussion
-   `here <https://pysat.readthedocs.io/en/main/new_instrument.html#testing-support>`_
+   [here](https://pysat.readthedocs.io/en/main/new_instrument.html#testing-support)
    for more information on triggering these standard tests.
 
    Tests for custom functions should be added to the appropriately named file
@@ -63,21 +78,32 @@ To set up `pysatNASA` for local development:
 
 
 4. When you're done making changes, run all the checks to ensure that nothing
-   is broken on your local system, as well as check for flake8 compliance::
+   is broken on your local system, as well as check for flake8 compliance:
 
+   ```
     pytest -vs --flake8 pysatNASA
+   ```
 
 5. Update/add documentation (in ``docs``), if relevant
 
 6. Add your name to the .zenodo.json file as an author
 
-7. Commit your changes and push your branch to GitHub::
-
-    git add .
-    git commit -m "Brief description of your changes"
-    git push origin name-of-your-bugfix-or-feature
-
-8. Submit a pull request through the GitHub website. Pull requests should be
+7. Commit your changes:
+   ```
+   git add .
+   git commit -m "AAA: Brief description of your changes"
+   ```
+   Where AAA is a standard shorthand for the type of change (eg, BUG or DOC).
+   `pysat` follows the [numpy development workflow](https://numpy.org/doc/stable/dev/development_workflow.html),
+   see the discussion there for a full list of this shorthand notation.  
+
+8. Once you are happy with the local changes, push to Github:
+   ```
+   git push origin name-of-your-bugfix-or-feature
+   ```
+   Note that each push will trigger the Continuous Integration workflow.
+
+9. Submit a pull request through the GitHub website. Pull requests should be
    made to the ``develop`` branch.
 
 Pull Request Guidelines
@@ -91,44 +117,46 @@ For merging, you should:
 1. Include an example for use
 2. Add a note to ``CHANGELOG.md`` about the changes
 3. Update the author list in ``zenodo.json`` if applicable
-4. Ensure that all checks passed (current checks include Travis-CI (pytest and
-   flake8) and Coveralls) [1]_
-
-.. [1] If you don't have all the necessary Python versions available locally or
-      have trouble building all the testing environments, you can rely on
-      Travis to run the tests for each change you add in the pull request.
-      Because testing here will delay tests by other developers, please ensure
-      that the code passes all tests on your local system first.
-
- Project Style Guidelines
- ------------------------
-
- In general, pysat follows PEP8 and numpydoc guidelines.  Pytest runs the unit
- and integration tests, flake8 checks for style, and sphinx-build performs
- documentation tests.  However, there are certain additional style elements that
- have been adopted to ensure the project maintains a consistent coding style.
- These include:
-
- * Line breaks should occur before a binary operator (ignoring flake8 W503)
- * Combine long strings using `join`
- * Preferably break long lines on open parentheses rather than using `\`
- * Use no more than 80 characters per line
- * Avoid using Instrument class key attribute names as unrelated variable names:
-   `platform`, `name`, `tag`, and `inst_id`
- * The pysat logger is imported into each sub-module and provides status updates
-   at the info and warning levels (as appropriate)
- * Several dependent packages have common nicknames, including::
-   * `import datetime as dt`
-   * `import numpy as np`
-   * `import pandas as pds`
-   * `import xarray as xr`
- * All classes should have `__repr__` and `__str__` functions
- * Docstrings use `Note` instead of `Notes`
- * Try to avoid creating a try/except statement where except passes
- * Use setup and teardown in test classes
- * Use pytest parametrize in test classes when appropriate
- * Provide testing class methods with informative failure statements and
-   descriptive, one-line docstrings
- * Block and inline comments should use proper English grammar and punctuation
-   with the exception of single sentences in a block, which may then omit the
-   final period
+4. Ensure that all checks passed (current checks include Github Actions and Coveralls)
+
+If you don't have all the necessary Python versions available locally or
+have trouble building all the testing environments, you can rely on
+GitHub Actions to run the tests for each change you add in the pull
+request. Because testing here will delay tests by other developers,
+please ensure that the code passes all tests on your local system first.
+
+
+Project Style Guidelines
+------------------------
+
+In general, pysat follows PEP8 and numpydoc guidelines.  Pytest runs the unit
+and integration tests, flake8 checks for style, and sphinx-build performs
+documentation tests.  However, there are certain additional style elements that
+have been adopted to ensure the project maintains a consistent coding style.
+These include:
+
+* Line breaks should occur before a binary operator (ignoring flake8 W503)
+* Combine long strings using `join`
+* Preferably break long lines on open parentheses rather than using `\`
+* Use no more than 80 characters per line
+* Avoid using Instrument class key attribute names as unrelated variable names:
+  `platform`, `name`, `tag`, and `inst_id`
+* The pysat logger is imported into each sub-module and provides status updates
+  at the info and warning levels (as appropriate)
+* Several dependent packages have common nicknames, including:
+  * `import datetime as dt`
+  * `import numpy as np`
+  * `import pandas as pds`
+  * `import xarray as xr`
+* When incrementing a timestamp, use `dt.timedelta` instead of `pds.DateOffset`
+  when possible to reduce program runtime
+* All classes should have `__repr__` and `__str__` functions
+* Docstrings use `Note` instead of `Notes`
+* Try to avoid creating a try/except statement where except passes
+* Use setup and teardown in test classes
+* Use pytest parametrize in test classes when appropriate
+* Provide testing class methods with informative failure statements and
+  descriptive, one-line docstrings
+* Block and inline comments should use proper English grammar and punctuation
+  with the exception of single sentences in a block, which may then omit the
+  final period

docs/examples/ex_init.rst

@@ -13,7 +13,8 @@ Meter on board the Ionospheric CONnection Explorer `(ICON) <https://www.nasa.gov
    import datetime as dt
    import pysat
    import pysatNASA as py_nasa
-pysat.utils.registry.register_by_module(py_nasa.instruments)
+
+   pysat.utils.registry.register_by_module(py_nasa.instruments)
 
    old_time = dt.datetime(2020, 1, 1)
    ivm = pysat.Instrument(platform='icon', name='ivm',

pysatNASA/instruments/de2_lang.py

@@ -48,10 +48,6 @@
 - Currently no cleaning routine.
 
 
-Authors
--------
-J. Klenzing
-
 """
 
 import datetime as dt

pysatNASA/instruments/de2_nacs.py

@@ -72,10 +72,6 @@
 --------
 - Currently no cleaning routine.
 
-Authors
--------
-J. Klenzing
-
 """
 
 import datetime as dt

pysatNASA/instruments/de2_rpa.py

@@ -57,10 +57,6 @@
 --------
 - Currently no cleaning routine.
 
-Authors
--------
-J. Klenzing
-
 """
 
 import datetime as dt

pysatNASA/instruments/de2_wats.py

@@ -68,10 +68,6 @@
 --------
 - Currently no cleaning routine.
 
-Authors
--------
-J. Klenzing
-
 """
 
 import datetime as dt

pysatNASA/instruments/icon_euv.py

@@ -36,11 +36,6 @@
     euv = pysat.Instrument(platform='icon', name='euv',
                            keep_original_names=True)
 
-Authors
----------
-Jeff Klenzing, Mar 17, 2018, Goddard Space Flight Center
-Russell Stoneback, Mar 23, 2018, University of Texas at Dallas
-
 """
 
 import datetime as dt

pysatNASA/instruments/icon_fuv.py

@@ -35,13 +35,6 @@
     fuv = pysat.Instrument(platform='icon', name='fuv', tag=day',
                            keep_original_names=True)
 
-Authors
--------
-Originated from EUV support.
-Jeff Klenzing, Mar 17, 2018, Goddard Space Flight Center
-Russell Stoneback, Mar 23, 2018, University of Texas at Dallas
-Conversion to FUV, Oct 8th, 2028, University of Texas at Dallas
-
 """
 
 import datetime as dt

pysatNASA/instruments/icon_mighti.py

@@ -43,13 +43,6 @@
                               clean_level='clean',
                               keep_original_names=True)
 
-Authors
--------
-Originated from EUV support.
-Jeff Klenzing, Mar 17, 2018, Goddard Space Flight Center
-Russell Stoneback, Mar 23, 2018, University of Texas at Dallas
-Conversion to MIGHTI, Oct 8th, 2018, University of Texas at Dallas
-
 Note
 ----
 Currently red and green data products are bundled together in zip files on the

pysatNASA/instruments/ses14_gold.py

@@ -29,11 +29,6 @@
     nmax.download(dt.datetime(2020, 1, 1), dt.datetime(2020, 1, 31))
     nmax.load(2020, 1)
 
-
-Authors
----------
-Jeff Klenzing, Oct 06, 2020, Goddard Space Flight Center
-
 """
 
 import datetime as dt

pysatNASA/instruments/templates/template_cdaweb_instrument.py

@@ -36,11 +36,6 @@
 
     Example code can go here
 
-
-Authors
--------
-Author name and institution
-
 """
 
 import datetime as dt

pysatNASA/instruments/timed_saber.py

@@ -41,11 +41,6 @@
 - Note on Temperature Errors: http://saber.gats-inc.com/temp_errors.php
 - No cleaning routine
 
-
-Authors
--------
-J. Klenzing, 4 March 2019
-
 """
 
 import datetime as dt

test_requirements.txt

@@ -2,11 +2,11 @@ coveralls<3.3
 flake8
 flake8-docstrings
 hacking>=1.0
+ipython
+m2r2
+numpydoc
 pytest
 pytest-cov
 pytest-ordering
 sphinx
 sphinx_rtd_theme
-numpydoc
-ipython
-m2r2