Merge pull request #112 from pysat/sty/docs

STY: docs standards

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,29 +1,29 @@
 ---
 name: Bug report
 about: Create a report to help us improve
+labels: bug
+title: "BUG: "
 
 ---
 
-**Describe the bug**
-A clear and concise description of what the bug is.
+# Description
+A clear and concise description of what the bug is, including a description
+of what you expected the outcome to be.
 
-**To Reproduce**
+# To Reproduce this bug:
 Steps to reproduce the behavior:
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
 4. See error
 
-**Expected behavior**
-A clear and concise description of what you expected to happen.
+Consider including images or test files to help others reproduce the bug and
+solve the problem.
 
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
-
-**Desktop (please complete the following information):**
- - OS: [e.g. iOS]
- - Version [e.g. 22]
+## Test configuration
+ - OS: [e.g. Hal]
+ - Version: [e.g. Python 3.47]
  - Other details about your setup that could be relevant
 
-**Additional context**
-Add any other context about the problem here.
+# Additional context
+Add any other context about the problem here, including expected behaviour.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,17 +1,27 @@
 ---
 name: Feature request
 about: Suggest an idea for this project
+title: "ENH: "
+labels: enhancement
 
 ---
 
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+# Description
+A clear and concise description of the new feature or behaviour you would like.
 
-**Describe the solution you'd like**
+## Potential impact
+
+- Is the feature related to an existing problem?
+- How critical is this feature to your workflow?
+- How wide of an impact to you anticipate this enhancement having?
+- Would this break any existing functionality?
+
+## Potential solution(s)
 A clear and concise description of what you want to happen.
 
-**Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
+# Alternatives
+A clear description of any alternative solutions or features you've considered.
 
-**Additional context**
-Add any other context or screenshots about the feature request here.
+# Additional context
+Add any other context or screenshots about the feature request here, potentially
+including your operational configuration.

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,19 @@
+---
+name: Question
+about: A question about this project
+title: "QUEST: "
+labels: question
+
+---
+
+# Description
+A clear and concise summary of your query
+
+## Example code (optional)
+If relevant, include sample code, images, or files so that others can understand
+the full context of your question.
+
+## Configuration
+ - OS: [e.g. Hal]
+ - Version: [e.g. Python 3.47]
+ - Other details about your setup that could be relevant

.github/pull_request_template.md

@@ -25,9 +25,9 @@ your test configuration
 - Test A
 - Test B
 
-**Test Configuration**:
-* Operating system
-* Version number
+## Test Configuration
+* Operating system: Hal
+* Version number: Python 3.X
 * Any details about your local setup that are relevant
 
 # Checklist:
@@ -42,3 +42,8 @@ your test configuration
 - [ ] New and existing unit tests pass locally with my changes
 - [ ] Any dependent changes have been merged and published in downstream modules
 - [ ] Add a note to ``CHANGELOG.md``, summarizing the changes
+- [ ] Update zenodo.json file for new code contributors
+
+If this is a release PR, replace the first item of the above checklist with the
+release checklist on the pysat wiki:
+https://github.com/pysat/pysat/wiki/Checklist-for-Release

.github/workflows/docs.yml

@@ -8,11 +8,11 @@ on: [push, pull_request]
 jobs:
   build:
 
-    runs-on: ubuntu-latest
+    runs-on: ["ubuntu-latest"]
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.9]
+        python-version: ["3.9"]
 
     name: Documentation tests
     steps:

CHANGELOG.md

@@ -15,6 +15,7 @@ This project adheres to [Semantic Versioning](https://semver.org/).
   * Add tests for Mac OS
   * Deprecate `calculate_ecef_velocity` method
   * Use pyproject.toml to handle metadata / installation
+  * Update GitHub Actions workflow standards
 * Testing
   * Include checks on sc coordinate transformation calculations
 

CONTRIBUTING.md

@@ -13,6 +13,7 @@ Short version
 -------------
 
 * Submit bug reports and feature requests at [GitHub](https://github.com/pysat/pysatMissions/issues)
+
 * Make pull requests to the ``develop`` branch
 
 Bug reports
@@ -22,7 +23,9 @@ When [reporting a bug](https://github.com/pysat/pysatMissions/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
@@ -34,7 +37,9 @@ The best way to send feedback is to file an issue at
 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 :)
 
@@ -55,40 +60,53 @@ 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``.  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_``.
+   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``.  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_`` as well.
 
 4. When you're done making changes, run all the checks to ensure that nothing
    is broken on your local system:
    ```
    pytest -vs
    ```
 
-5. Update/add documentation (in ``docs``), if relevant
+   5. You should also check for flake8 style compliance:
 
-6. Add your name to the .zenodo.json file as an author
+      ```
+      flake8 . --count --select=D,E,F,H,W --show-source --statistics
+      ```
 
-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.  
+      Note that pysat uses the `flake-docstrings` and `hacking` packages to ensure
+      standards in docstring formatting.
 
-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.
+   6. Update/add documentation (in ``docs``), if relevant
+
+   7. Add your name to the .zenodo.json file as an author
+
+   8. 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.  
+
+   9. 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.
+
+   10. Submit a pull request through the GitHub website. Pull requests should be
+       made to the ``develop`` branch.  Note that automated tests will be run on
+       GitHub Actions, but these must be initialized by a member of the pysat team.
+
 
 Pull Request Guidelines
 -----------------------
@@ -100,17 +118,19 @@ For merging, you should:
 
 1. Include an example for use
 2. Add a note to ``CHANGELOG.md`` about the changes
-3. Ensure that all checks passed (current checks include GitHub Actions
-   and Coveralls)
+3. Update the author list in ``zenodo.json`` if applicable
+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
-the project's Continuous Integration (CI) service to run the tests for each change you add in the pull
+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

docs/conf.py

@@ -98,6 +98,7 @@
 # a list of builtin themes.
 #
 html_theme = 'sphinx_rtd_theme'
+html_theme_path = ["_themes", ]
 
 # 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
@@ -124,7 +125,7 @@
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'pysatMissionsdoc'
+htmlhelp_basename = '{:s}doc'.format(project)
 
 
 # -- Options for LaTeX output ------------------------------------------------
@@ -173,6 +174,9 @@
 
 # Bibliographic Dublin Core info.
 epub_title = project
+epub_author = author
+epub_publisher = author
+epub_copyright = copyright
 
 # The unique identifier of the text. This can be a ISBN number
 # or the project homepage.