Merge pull request #24 from e-lo/PR-issue-templates

- adds Workflows for doc gen, linting and testing
- updates docs to mkdocs
- adds governance, contribution guideines
- adds PR and issue templates
- adds pre-commit and linting

Closes: #22 #23 #21

.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,13 @@
+---
+name: Bug report
+about: Create a report to help us improve the project code
+title: '🐛  '
+labels: ['🐛 bug']
+assignees: ''
+
+---
+## Describe the problem
+<!-- A clear and concise description of the problem, what result did you expect, what did you get? -->
+
+## Steps to reproduce
+<!-- Describe the steps required to reproduce the problem, see <https://stackoverflow.com/help/minimal-reproducible-example>  -->

.github/ISSUE_TEMPLATE/feature.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest and idea for the project code
+title: '🚀 '
+labels: ['🚀 feature']
+assignees: ''
+---
+
+## Describe the feature you want and how it meets your needs or solves a problem
+<!-- Your user story, https://tech.gsa.gov/guides/effective_user_stories/ -->
+As a <!-- type of user -->, I want <!-- some goal, function --> so that <!-- some reason -->.
+
+## Describe the solution you'd like
+<!-- 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. -->
+
+## Additional context
+<!-- Add any other context for the feature request here. -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+<Before submitting a pull request, please read [CONTRIBUTING.md](CONTRIBUTING.md).>
+
+## Code Submission Checklist
+
+- [ ] All public API changes, usage, and architecture changes are documented
+- [ ] All functions and modules have been documented using [google-style docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
+- [ ] Code and documentation linted: `pre-commit run --all-files`
+- [ ] Code for this PR is covered in tests
+- [ ] Code passes all tests: `pytest`
+- [ ] By contributing to this project, all contributors certify to the Developer Certificate of Origin in [CONTRIBUTING.md](CONTRIBUTING.md#contributor-agreement).
+
+## Documentation Submission Checklist
+
+- [ ] Documentation can be built locally `mkdocs build`
+- [ ] Documentation has been reviewed locally `mkdocs serve`
+- [ ] By contributing to this project, all contributors certify to the Developer Certificate of Origin in [CONTRIBUTING.md](CONTRIBUTING.md#contributor-agreement).
+
+## Applicable Issues
+*Please do not create a Pull Request without creating an issue first.*
+
+*Put `closes #XXXX` in your comment to auto-close the issue that your PR fixes.*
+
+
+#### Issues List
+
+ -  closes...
+ -  closes...

.github/workflows/clean-docs.yml

@@ -0,0 +1,29 @@
+name: Clean Docs for Deleted References
+on:
+  delete:
+env:
+    DOC_REF_NAME: ${{ github.head_ref || github.ref_name }}
+jobs:
+  clean:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+    - name: Set up Python $PYTHON_VERSION
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+        cache: 'pip'
+    - name: Install Mike
+      run: |
+        python -m pip install --upgrade pip
+        pip install mike
+    - name: Configure Git user
+      run: |
+        git config --local user.email "github-actions[bot]@users.noreply.github.com"
+        git config --local user.name "github-actions[bot]"
+    - name: Delete defunct docs versions
+      run: |
+        echo "Deleting $DOC_REF_NAME version from docs"
+        mike delete --rebase --push $ DOC_REF_NAME

.github/workflows/documentation.yml

@@ -1,35 +1,46 @@
 name: Build docs on push
 
-on: 
-  pull_request:
+on:
   release:
     types: [created]
   push:
-    branches:
-      - master
+    branches: [develop, main]
+  workflow_dispatch:
 
+env:
+ DOC_REF_NAME: ${{ github.head_ref || github.ref_name }}
 jobs:
-  build-deploy:
+  build-deploy-docs:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v2
       with:
         fetch-depth: 0
     - name: Document which branch
-      run: echo ${{ github.ref_name }}
+      run: echo $DOC_REF_NAME
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v2
       with:
         python-version: '3.x'
         cache: 'pip'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         pip install -r docs/requirements.txt
+    - name: Install package
+      run: |
+        pip install -e .
     - name: Configure Git user
       run: |
         git config --local user.email "github-actions[bot]@users.noreply.github.com"
         git config --local user.name "github-actions[bot]"
+        git fetch origin gh-pages --depth=1
     - name: Build docs
       run: |
-        mike deploy --push --rebase ${{ github.ref_name }}
+        mike deploy --push --rebase $DOC_REF_NAME
+    - name: add comment to PR with documentation link
+      if: github.event_name != 'pull_request'
+      uses: mshick/add-pr-comment@v2
+      with:
+        message: |
+          Preview documentation at: <https://e-lo.github.io/GMNSpy/$DOC_REF_NAME>

.github/workflows/pythonpublish.yml

@@ -4,36 +4,31 @@
 name: Upload Python Package
 
 on:
-  pull_request:
   release:
     types: [created]
 
 jobs:
   deploy:
-
     runs-on: ubuntu-latest
-
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Set up Python
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v4
       with:
         python-version: '3.x'
+        cache: 'pip'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         pip install setuptools wheel twine
-
     - name: Build
       run: python setup.py sdist bdist_wheel
-
     - name: Keeps wheel on GitHub
       uses: actions/upload-artifact@v2
       with:
         name: package
         path: dist/*
         if-no-files-found: error # 'warn' or 'ignore' are also available, defaults to `warn`
-
     - name: Publish
       if: github.event_name == 'release'
       env:

.github/workflows/tests.yml

@@ -10,39 +10,34 @@ jobs:
       matrix:
         python-version: ['3.10']
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v1
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
       with:
-        python-version: ${{ matrix.python-version }}
-    - name: Lint with flake8
-      run: |
-        pip install flake8
-        flake8
-
-    - name: Check code format with Black
-      run: |
-        pip install black
-        black --check .
-
-  unittests:
+        python-version: 3.x
+    - uses: pre-commit/[email protected]
+      with:
+        extra_args: --all-files --verbose
+  tests:
     needs: linting
     runs-on: ubuntu-latest
     strategy:
       max-parallel: 4
       matrix:
         python-version: ['3.10']
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
+        cache: 'pip'
     - name: install dependencies
       run: |
         pip install -r requirements.txt
         pip install pytest
-
+    - name: Install package
+      run: |
+        pip install -e .
     - name: Runs tests
       run: |
-        python -m pytest
+        pytest

.gitignore

@@ -6,9 +6,6 @@ __pycache__/
 # C extensions
 *.so
 
-# Generated documentation files
-docs/_generated/**
-
 # Distribution / packaging
 .Python
 build/

.pre-commit-config.yaml

@@ -0,0 +1,48 @@
+default_stages: [commit]
+repos:
+  - repo: https://github.com/psf/black
+    rev: 22.3.0
+    hooks:
+      - id: black
+        language_version: python3
+      - id: black-jupyter
+  - repo: https://github.com/PyCQA/pydocstyle
+    rev: 6.1.1
+    hooks:
+      - id: pydocstyle
+        stages: [manual]
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v3.4.0
+    hooks:
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: check-added-large-files
+      - id: check-json
+      - id: pretty-format-json
+        args: [--autofix]
+      - id: check-toml
+      - id: check-yaml
+        args: [--unsafe]
+      - id: requirements-txt-fixer
+      - id: check-executables-have-shebangs
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.27.1
+    hooks:
+      - id: markdownlint
+        stages: [manual]
+  - repo: https://github.com/pycqa/isort
+    rev: 5.12.0
+    hooks:
+    - id: isort
+      args: ["--profile", "black"]
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: 0.14.3
+    hooks:
+    - id: check-github-workflows
+  - repo: http://github.com/pycqa/flake8
+    rev: 4.0.1
+    hooks:
+    - id: flake8
+      stages: [manual]

CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ an individual is officially representing the community in public spaces.
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to @e-lo or 
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to @e-lo or
 other package maintainers.
 
 All complaints will be reviewed and investigated promptly and fairly.

CONTRIBUTING.md

@@ -44,6 +44,7 @@ Generally:
 - Be compatable with Numpy 2+, Pandas 2+, OSMNX 1+, PyProj 3.3+
 - Use PEP8 and autoformat with `black`
 - Use Google-style docstrings for all classes and methods
+- Test formatting and autoformat using `pre-commit`
 - Use logging
 - All code should have an associated test
 - [Documentation](#documentation) is in the `docs` folder and is built using `mkdocs`
@@ -122,4 +123,4 @@ By making a contribution to this project, I certify that:
 >  
 > d. I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
 >  
-Attribution: This Contributor Agreement is adapted from the node.js project available here: <https://github.com/nodejs/node/blob/main/CONTRIBUTING.md>.
+Attribution: This Contributor Agreement is adapted from the node.js project available here: <https://github.com/nodejs/node/blob/main/CONTRIBUTING.md>.

dev-requirements.txt

@@ -1,10 +1,6 @@
-sphinx
-pytest
-sphinx-autodoc-typehints
-sphinx_rtd_theme
+autoflake
 black
-recommonmark
-sphinx-markdown-tables
 flake8
-graphviz
-tabulate
+pre-commit
+pydocstyle
+pytest

docs/architecture.md

@@ -1,2 +1,2 @@
 
-To come.
+To come.

docs/development.md

@@ -4,4 +4,4 @@
 
 {{ include_file('CODE_OF_CONDUCT.md') }}
 
-{{ include_file('contributors.md') }}
+{{ include_file('CONTRIBUTORS.md') }}

docs/requirements.txt

@@ -8,4 +8,4 @@ mkdocs-material
 mkdocs-mermaid2-plugin
 mkdocs-redirects
 pandas
-tabulate
+tabulate

gmnspy/__init__.py

@@ -1,3 +1,27 @@
-from .in_out import *
-from .schema import *
+"""GMNSpy package.
+
+Typical usage:
+
+    ```python
+    import gmnspy
+    ```
+"""
+
+from .in_out import read_gmns_csv, read_gmns_network
+from .schema import (
+    document_schemas_to_md,
+    document_spec_to_md,
+    read_config,
+    read_schema,
+)
 from .utils import list_to_md_table, logger
+
+__all__ = [
+    "read_gmns_csv",
+    "read_gmns_network",
+    "document_schemas_to_md",
+    "document_spec_to_md",
+    "read_config," "read_schema",
+    "list_to_md_table",
+    "logger",
+]