From 83c822e2a5d1f3dbf464589cc628be55a105d451 Mon Sep 17 00:00:00 2001 From: Scott Griv Date: Thu, 23 Nov 2023 22:11:20 -0500 Subject: [PATCH] Add extra GitHub files, update README --- .github/CHANGELOG.md | 18 ++ .github/CODEOWNERS | 1 + .github/CODE_OF_CONDUCT.md | 70 ++++++++ .github/CONTRIBUTING.md | 159 +++++++++++++++++ .github/CREDITS | 17 ++ .github/FUNDING.yml | 14 ++ .github/ISSUE_TEMPLATE/bug_report.md | 38 ++++ .github/ISSUE_TEMPLATE/feature_request.md | 20 +++ .github/PULL_REQUEST_TEMPLATE.md | 19 ++ .github/SECURITY.md | 11 ++ .github/SUPPORT.md | 63 +++++++ CREDIT | 14 -- README.md | 201 ++++++++++++---------- VERSION | 1 - 14 files changed, 542 insertions(+), 104 deletions(-) create mode 100644 .github/CHANGELOG.md create mode 100644 .github/CODEOWNERS create mode 100644 .github/CODE_OF_CONDUCT.md create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/CREDITS create mode 100644 .github/FUNDING.yml create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/SECURITY.md create mode 100644 .github/SUPPORT.md delete mode 100644 CREDIT delete mode 100644 VERSION diff --git a/.github/CHANGELOG.md b/.github/CHANGELOG.md new file mode 100644 index 0000000..1ab3bda --- /dev/null +++ b/.github/CHANGELOG.md @@ -0,0 +1,18 @@ +# Changelog + +## v1.0.0 + +### Added or Changed +- Added this changelog file :D +- Initial Release of River Charts + +### Removed +- N/A + +## v1.1.0 + +### Added or Changed +- Updated README and repo structure to conform to the [Personal Repository Guidelines (PRG)](https://github.com/scottgriv/PRG-Personal-Repository-Guidelines) system. + +### Removed +- VERSION file \ No newline at end of file diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..c5e36e1 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +@scottgriv \ No newline at end of file diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..47c5e5b --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,70 @@ +# Code of Conduct - River Charts + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to make participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, or to ban +temporarily or permanently any contributor for other behaviors that they deem +inappropriate, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at . +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://contributor-covenant.org/), version +[1.4](https://www.contributor-covenant.org/version/1/4/code-of-conduct/code_of_conduct.md) and +[2.0](https://www.contributor-covenant.org/version/2/0/code_of_conduct/code_of_conduct.md), +and was generated by [contributing-gen](https://github.com/bttger/contributing-gen). \ No newline at end of file diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..975ac78 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,159 @@ + +# Contributing to River Charts + +First off, thanks for taking the time to contribute! ❀️ + +All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. πŸŽ‰ + +> And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about: +> - Star the project +> - Tweet about it +> - Refer this project in your project's readme +> - Mention the project at local meetups and tell your friends/colleagues + + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [I Have a Question](#i-have-a-question) +- [I Want To Contribute](#i-want-to-contribute) + - [Reporting Bugs](#reporting-bugs) + - [Suggesting Enhancements](#suggesting-enhancements) + - [Your First Code Contribution](#your-first-code-contribution) + - [Improving The Documentation](#improving-the-documentation) +- [Styleguides](#styleguides) + - [Commit Messages](#commit-messages) +- [Join The Project Team](#join-the-project-team) + + +## Code of Conduct + +This project and everyone participating in it is governed by the +[River Charts Code of Conduct](CODE_OF_CONDUCT.md). +By participating, you are expected to uphold this code. Please report unacceptable behavior +to . + + +## I Have a Question + +> If you want to ask a question, we assume that you have read the available [Documentation](). + +Before you ask a question, it is best to search for existing [Issues](https://github.com/scottgriv/River-Charts/issues) that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first. + +If you then still feel the need to ask a question and need clarification, we recommend the following: + +- Open an [Issue](https://github.com/scottgriv/River-Charts/issues/new). +- Provide as much context as you can about what you're running into. +- Provide project and platform versions (nodejs, npm, etc), depending on what seems relevant. + +We will then take care of the issue as soon as possible. + + + +## I Want To Contribute + +> ### Legal Notice +> When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license. + +### Reporting Bugs + + +#### Before Submitting a Bug Report + +A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information and describe the issue in detail in your report. Please complete the following steps in advance to help us fix any potential bug as fast as possible. + +- Make sure that you are using the latest version. +- Determine if your bug is really a bug and not an error on your side e.g. using incompatible environment components/versions (Make sure that you have read the [documentation](). If you are looking for support, you might want to check [this section](#i-have-a-question)). +- To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the [bug tracker](https://github.com/scottgriv/River-Charts/issues?q=label%3Abug). +- Also make sure to search the internet (including Stack Overflow) to see if users outside of the GitHub community have discussed the issue. +- Collect information about the bug: + - Stack trace (Traceback) + - OS, Platform and Version (Windows, Linux, macOS, x86, ARM) + - Version of the interpreter, compiler, SDK, runtime environment, package manager, depending on what seems relevant. + - Possibly your input and the output + - Can you reliably reproduce the issue? And can you also reproduce it with older versions? + + +#### How Do I Submit a Good Bug Report? + +> You must never report security related issues, vulnerabilities or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead sensitive bugs must be sent by email to . + + +We use GitHub issues to track bugs and errors. If you run into an issue with the project: + +- Open an [Issue](https://github.com/scottgriv/River-Charts/issues/new). (Since we can't be sure at this point whether it is a bug or not, we ask you not to talk about a bug yet and not to label the issue.) +- Explain the behavior you would expect and the actual behavior. +- Please provide as much context as possible and describe the *reproduction steps* that someone else can follow to recreate the issue on their own. This usually includes your code. For good bug reports you should isolate the problem and create a reduced test case. +- Provide the information you collected in the previous section. + +Once it's filed: + +- The project team will label the issue accordingly. +- A team member will try to reproduce the issue with your provided steps. If there are no reproduction steps or no obvious way to reproduce the issue, the team will ask you for those steps and mark the issue as `needs-repro`. Bugs with the `needs-repro` tag will not be addressed until they are reproduced. +- If the team is able to reproduce the issue, it will be marked `needs-fix`, as well as possibly other tags (such as `critical`), and the issue will be left to be [implemented by someone](#your-first-code-contribution). + + + + +### Suggesting Enhancements + +This section guides you through submitting an enhancement suggestion for River Charts, **including completely new features and minor improvements to existing functionality**. Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions. + + +#### Before Submitting an Enhancement + +- Make sure that you are using the latest version. +- Read the [documentation]() carefully and find out if the functionality is already covered, maybe by an individual configuration. +- Perform a [search](https://github.com/scottgriv/River-Charts/issues) to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one. +- Find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Keep in mind that we want features that will be useful to the majority of our users and not just a small subset. If you're just targeting a minority of users, consider writing an add-on/plugin library. + + +#### How Do I Submit a Good Enhancement Suggestion? + +Enhancement suggestions are tracked as [GitHub issues](https://github.com/scottgriv/River-Charts/issues). + +- Use a **clear and descriptive title** for the issue to identify the suggestion. +- Provide a **step-by-step description of the suggested enhancement** in as many details as possible. +- **Describe the current behavior** and **explain which behavior you expected to see instead** and why. At this point you can also tell which alternatives do not work for you. +- You may want to **include screenshots and animated GIFs** which help you demonstrate the steps or point out the part which the suggestion is related to. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux. +- **Explain why this enhancement would be useful** to most River Charts users. You may also want to point out the other projects that solved it better and which could serve as inspiration. + + + +### Your First Code Contribution + + +### Improving The Documentation + + +## Styleguides +### Commit Messages + + +## Join The Project Team + + + +## Attribution +This guide is based on the **contributing-gen**. [Make your own](https://github.com/bttger/contributing-gen)! diff --git a/.github/CREDITS b/.github/CREDITS new file mode 100644 index 0000000..53f4bdb --- /dev/null +++ b/.github/CREDITS @@ -0,0 +1,17 @@ +This file is a list of people who have contributed to the River Charts +project. If you have contributed a pull request or made some other contribution to +River Charts, please submit a pull request with this file with yourself added to it, thanks! + +The list is sorted by surname and formatted to allow easy grepping and +beautification by scripts. + +The fields are: +(N) name +(E) email +(W) website +(D) description + +N: Scott Grivner +E: scott.grivner@gmail.com +W: https://www.scottgrivner.dev +D: Original Creator and Developer of River Charts \ No newline at end of file diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..24d8b80 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,14 @@ +# Docs: https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/displaying-a-sponsor-button-in-your-repository + +# These are supported funding model platforms +github: [scottgriv] +custom: ["https://www.buymeacoffee.com/scottgriv"] +# patreon: # Replace with a single Patreon username +# open_collective: # Replace with a single Open Collective username +# ko_fi: # Replace with a single Ko-fi username +# tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel +# community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry +# liberapay: # Replace with a single Liberapay username +# issuehunt: # Replace with a single IssueHunt username +# otechie: # Replace with a single Otechie username +# custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2'] \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..dd84ea7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,38 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '' +labels: '' +assignees: '' + +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**To Reproduce** +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. + +**Screenshots** +If applicable, add screenshots to help explain your problem. + +**Desktop (please complete the following information):** + - OS: [e.g. iOS] + - Browser [e.g. chrome, safari] + - Version [e.g. 22] + +**Smartphone (please complete the following information):** + - Device: [e.g. iPhone6] + - OS: [e.g. iOS8.1] + - Browser [e.g. stock browser, safari] + - Version [e.g. 22] + +**Additional context** +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..bbcbbe7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: '' +labels: '' +assignees: '' + +--- + +**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 [...] + +**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 or screenshots about the feature request here. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..fdb3249 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,19 @@ +## PR Purpose + +The context for this pull request or the [Conventional Commits type](https://github.com/commitizen/conventional-commit-types/blob/master/index.json) that best matches the changes. + +## Changes Summary + +Summarize what you've changed and **why**. Make sure to mention if this is a **breaking change.** + +## Screenshots + +Add screenshots of the feature in action or a video/GIF walkthrough of the UX. Remove if not applicable (e.g. refactoring). + +## Areas of interest + +Edge cases, workarounds, hacks, security concerns, and other areas of the code you'd like the reviewer to pay extra attention to or give feedback on. + +--- + +[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org/) \ No newline at end of file diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..10c3fc5 --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,11 @@ +# Security Policy + +## Reporting a Vulnerability + +If you discover a security issue, please report it by sending an +email to scott.grivner@gmail.com + +This will allow us to assess the risk, and make a fix available before we add a +bug report to the GitHub repository. + +Thanks for helping make this project safe for everyone. \ No newline at end of file diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md new file mode 100644 index 0000000..fb7ae41 --- /dev/null +++ b/.github/SUPPORT.md @@ -0,0 +1,63 @@ +# Support + +This article explains where to get help with this project. +Please read through the following guidelines. + +> πŸ‘‰ **Note**: before participating in our community, please read our +> [Code of Conduct][coc]. +> By interacting with this repository, organization, or community you agree to +> abide by its terms. + +## Asking quality questions + +Questions can go to [GitHub Discussions][chat]. + +Help us help you! +Spend time framing questions and add links and resources. +Spending the extra time up front can help save everyone time in the long run. +Here are some tips: + +* [Talk to a Duck][rubberduck]! +* Don’t fall for the [XY problem][xy] +* Search to find out if a similar question has been asked +* Try to define what you need help with: + * Is there something in particular you want to do? + * What problem are you encountering and what steps have you taken to try + and fix it? + * Is there a concept you don’t understand? +* Provide sample code, such as a [CodeSandbox][cs] or video, if possible +* Screenshots can help, but if there’s important text such as code or error + messages in them, please also provide those as text +* The more time you put into asking your question, the better we can help you + +## How to file issues and get help + +This project uses GitHub Issues to track bugs and feature requests. +Please search the existing issues before filing new issues to avoid duplicates. +For new issues, file your bug or feature request as a new Issue. + +## Contributions + +See [`contributing.md`][contributing] on how to contribute. + +## License + +[CC-BY-4.0][license] Β© [@wooorm][author] + + + +[license]: https://creativecommons.org/licenses/by/4.0/ + +[author]: https://github.com/remarkjs/.github/blob/main/support.md + +[coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md + +[rubberduck]: https://rubberduckdebugging.com + +[xy]: https://meta.stackexchange.com/questions/66377/what-is-the-xy-problem/66378#66378 + +[chat]: https://github.com/scottgriv/River-Charts/discussions + +[cs]: https://codesandbox.io + +[contributing]: contributing.md \ No newline at end of file diff --git a/CREDIT b/CREDIT deleted file mode 100644 index fbdb53f..0000000 --- a/CREDIT +++ /dev/null @@ -1,14 +0,0 @@ -This file is a partial list of people who have contributed to the Post.e -project. If you have contributed a patch or made some other contribution to -River Charts, please submit a patch to this file to add yourself, and it will be -done! - -The list is sorted by surname and formatted to allow easy grepping and -beautification by scripts. The fields are: name (N), email (E), web-address -(W), PGP key ID and fingerprint (P), description (D), snail-mail address -(S), and (I) IRC handle. - -N: Scott Grivner -E: scott.grivner@gmail.com -W: https://www.scottgrivner.dev -D: Original Creator and Developer of River Charts \ No newline at end of file diff --git a/README.md b/README.md index 801ae43..d970dd6 100644 --- a/README.md +++ b/README.md @@ -3,36 +3,30 @@ [![App Logo](./docs/images/banner_large.png)](https://www.rivercharts.app)

- - Python Badge + Python Badge - - Django Badge + Django Badge - - Plotly Badge + Plotly Badge - - Pandas Badge + Pandas Badge
- - GitHub Badge + GitHub Badge - - Email Badge + Email Badge - - BuyMeACoffee Badge + BuyMeACoffee Badge - - Gold PRG Badge +
+ Gold PRG Badge

-------- +--------------- + +

River Charts

-# River Charts **River Charts** is a `Python`, `Django`, `Plotly`, and `Pandas` web application that visualizes river data for a specific river/site/location. - The line graph is driven by data pulled using an `API` from the [United States Geological Survey (USGS)](https://www.usgs.gov/). - The data is updated with the most recent river height data every time the application is loaded. @@ -46,22 +40,38 @@ Demo_2 -# Table of Contents -- [Background](#background) -- [Gage Height](#gage-height) -- [What's Inside?](#whats-inside) +--------------- + +## Table of Contents + +- [Features](#features) +- [Background Story](#background-story) + - [Gage Height](#gage-height) - [Dependencies](#dependencies) - [Getting Started](#getting-started) -- [Configuration](#configuration) -- [Deployment](#deployment) +- [What's Inside?](#whats-inside) - [Calling the API](#calling-the-api) - [API Output Example](#api-output-example) -- [Project](#project) - [Disclaimer](#disclaimer) +- [Project](#project) +- [Configuration](#configuration) +- [Deployment](#deployment) - [License](#license) - [Credit](#credit) -# Background +## Features + +- [x] **Responsive:** The application is responsive and can be used on a mobile device. +- [x] **Interactive:** The application uses `Plotly` to create an interactive line graph. +- [x] **Data Visualization:** The application visualizes river data for a specific river/site/location. +- [x] **Data Source:** The application sources data using an `API` that returns `JSON` output. +- [x] **Data Processing:** The application processes the `JSON` output and converts it to a `Pandas` `DataFrame`. +- [x] **Data Manipulation:** The application manipulates the `DataFrame` to create a `Plotly` line graph. +- [x] **Data Update:** The application updates the data with the most recent river height data every time the application is loaded. +- [x] **Data Capture:** The data is captured by the USGS using a [gage height](#gage-height) sensor every 15 minutes. + +## Background Story + Every year, my friends and I float 2 miles down the **Susquehanna River** in **NEPA** on river tubes (a 2 hour float). I wanted to create a web application that would allow us to visualize past river data in order to see the river height on the days we floated down the river. Some float dates, we still got together, but we didn't float due to the dangerous river levels. Green plots on the graph represent the dates we did float (with a "Floated" status of "Yes"), and Red plots represent the dates we did not float (with a "Floated" status of "No"). @@ -76,7 +86,8 @@ Every year, my friends and I float 2 miles down the **Susquehanna River** in **N West Branch, Susquehanna River. -## Gage Height +### Gage Height +
@@ -89,45 +100,8 @@ Every year, my friends and I float 2 miles down the **Susquehanna River** in **N The application uses gage height data to plot the river height in feet on a given date.
-## What's Inside? -A quick look at the important files and directories you'll see in this project: - -```bash -β”œβ”€β”€ README.md # This file. -β”œβ”€β”€ config.py # A file that contains sensitive information (excluded from this repository). -β”œβ”€β”€ manage.py # A command-line utility that lets you interact with this Django project in various ways. -β”œβ”€β”€ requirements.txt # A list of Python packages required to run this project. -β”œβ”€β”€ River_Charts # A directory for the river_charts app. -β”‚Β Β  β”œβ”€β”€ __init__.py # An empty file that tells Python that this directory should be considered a Python package. -β”‚Β Β  β”œβ”€β”€ admin.py # A file that registers models to be displayed in the Django admin site. -β”‚Β Β  β”œβ”€β”€ apps.py # A file that contains the application configuration. -β”‚Β Β  β”œβ”€β”€ models.py # A file that contains the database models. -β”‚Β Β  β”œβ”€β”€ tests.py # A file that contains the tests for the application. -β”‚Β Β  β”œβ”€β”€ urls.py # A file that contains the URL declarations for the application. -β”‚Β Β  └── views.py # A file that contains the application logic. -β”œβ”€β”€ river_charts # The Django project directory. -β”‚Β Β  β”œβ”€β”€ __init__.py # An empty file that tells Python that this directory should be considered a Python package. -β”‚Β Β  β”œβ”€β”€ asgi.py # An entry-point for ASGI-compatible web servers to serve your project. -β”‚Β Β  β”œβ”€β”€ settings.py # Settings/configuration for this Django project. -β”‚Β Β  β”œβ”€β”€ urls.py # The URL declarations for this Django project. -β”‚Β Β  └── wsgi.py # An entry-point for WSGI-compatible web servers to serve your project. -β”œβ”€β”€ static # A directory for static files that are used in this Django project. -β”‚Β Β  β”œβ”€β”€ css # A directory for CSS files. -β”‚Β Β  β”‚Β Β  └── styles.css # A CSS file that contains the styles for the application. -β”‚Β Β  β”œβ”€β”€ data # A directory for data files. -β”‚Β Β  β”‚Β Β  └── river_charts.csv # A CSV file that contains the float dates for the application. -β”‚Β Β  └── images # A directory for image files. -β”œβ”€β”€ templates # A directory for HTML templates. -β”‚Β Β  └── river_charts # A directory for HTML templates specific to the river_charts app. -β”‚Β Β  β”œβ”€β”€ error.html # An HTML template that displays an error message. -β”‚Β Β  └── index.html # An HTML template that displays the application. -β”œβ”€β”€ views.py # A file that contains the application logic. -β”œβ”€β”€ VERSION # A file that contains the current version of the application. -β”œβ”€β”€ LICENSE # A file that contains the license for this project. -└── CREDITS # A file that contains the credits for this project. -``` - ## Dependencies + This project makes use of several libraries and frameworks: - **Python:** For the application logic. - **Django:** For web application functionality. @@ -138,6 +112,7 @@ This project makes use of several libraries and frameworks: - *See [requirements.txt](requirements.txt) for a full list of dependencies.* ## Getting Started + To install and run the project locally, follow the steps below: 1. Clone the repository: @@ -183,28 +158,45 @@ To install and run the project locally, follow the steps below: Now, you can visit `http://127.0.0.1:8000/` in your browser to access the application. -## Configuration -- Edit `config.py` to add your own USGS `API` (and other) information. - - [USGS API](https://waterservices.usgs.gov/rest/IV-Service.html) - - [USGS API Documentation](https://help.waterdata.usgs.gov/faq/automated-retrievals) -- Toggle `USE_DUMMY_DATA` to `True` in `config.py` to use dummy data instead of the `API`. - - This is useful for testing the application without making `API` calls. -- The float data plots are driven from a `.csv` file located in `static/data/river_charts.csv`. - - This file can be edited to add/remove float dates. - - The file is read in `views.py` and passed to the template as a `context` variable. +## What's Inside? -## Deployment -- The application is hosted [here](https://www.rivercharts.app) on [PythonAnywhere](https://www.pythonanywhere.com/). -- The application is deployed using a `WSGI` configuration file. - - [WSGI Configuration](https://docs.djangoproject.com/en/3.2/howto/deployment/wsgi/) -- First, make sure you adjust your `settings.py` file `ALLOWED_HOSTS` to include your deployment host. - - [Deploying Django](https://docs.djangoproject.com/en/3.2/howto/deployment/) -- Second, make sure you adjust your `settings.py` file `DEBUG` to `False` for production. - - [Django Settings](https://docs.djangoproject.com/en/3.2/ref/settings/) -- Finnaly, be sure to create a `.env` file where you host your application to store your sensitive information (excluded from this repository). - - [Python-Decouple](https://pypi.org/project/python-decouple/) +Below is a list of the main files and folders in this repository and their specific purposes: +```bash +River-Charts # Root folder +β”œβ”€β”€ README.md # This file. +β”œβ”€β”€ config.py # A file that contains sensitive information (excluded from this repository). +β”œβ”€β”€ manage.py # A command-line utility that lets you interact with this Django project in various ways. +β”œβ”€β”€ requirements.txt # A list of Python packages required to run this project. +β”œβ”€β”€ River_Charts # A directory for the river_charts app. +β”‚Β Β  β”œβ”€β”€ __init__.py # An empty file that tells Python that this directory should be considered a Python package. +β”‚Β Β  β”œβ”€β”€ admin.py # A file that registers models to be displayed in the Django admin site. +β”‚Β Β  β”œβ”€β”€ apps.py # A file that contains the application configuration. +β”‚Β Β  β”œβ”€β”€ models.py # A file that contains the database models. +β”‚Β Β  β”œβ”€β”€ tests.py # A file that contains the tests for the application. +β”‚Β Β  β”œβ”€β”€ urls.py # A file that contains the URL declarations for the application. +β”‚Β Β  └── views.py # A file that contains the application logic. +β”œβ”€β”€ river_charts # The Django project directory. +β”‚Β Β  β”œβ”€β”€ __init__.py # An empty file that tells Python that this directory should be considered a Python package. +β”‚Β Β  β”œβ”€β”€ asgi.py # An entry-point for ASGI-compatible web servers to serve your project. +β”‚Β Β  β”œβ”€β”€ settings.py # Settings/configuration for this Django project. +β”‚Β Β  β”œβ”€β”€ urls.py # The URL declarations for this Django project. +β”‚Β Β  └── wsgi.py # An entry-point for WSGI-compatible web servers to serve your project. +β”œβ”€β”€ static # A directory for static files that are used in this Django project. +β”‚Β Β  β”œβ”€β”€ css # A directory for CSS files. +β”‚Β Β  β”‚Β Β  └── styles.css # A CSS file that contains the styles for the application. +β”‚Β Β  β”œβ”€β”€ data # A directory for data files. +β”‚Β Β  β”‚Β Β  └── river_charts.csv # A CSV file that contains the float dates for the application. +β”‚Β Β  └── images # A directory for image files. +β”œβ”€β”€ templates # A directory for HTML templates. +β”‚Β Β  └── river_charts # A directory for HTML templates specific to the river_charts app. +β”‚Β Β  β”œβ”€β”€ error.html # An HTML template that displays an error message. +β”‚Β Β  └── index.html # An HTML template that displays the application. +β”œβ”€β”€ views.py # A file that contains the application logic. +└── LICENSE # A file that contains the license for this project. +``` ## Calling the API + To call the `API` and retrieve the data: 1. Make a GET request to: `http://nwis.waterservices.usgs.gov/nwis/...` (based on your requirements). @@ -249,6 +241,7 @@ To call the `API` and retrieve the data: ## API Output Example + The application sources data using an `API` that returns `JSON` output. Here's an example of what the API response looks like: ```json @@ -282,23 +275,53 @@ The application sources data using an `API` that returns `JSON` output. Here's a ``` (For the sake of brevity, the full output is abbreviated with `...`) -## Project -Please reference the [GitHub Project](https://github.com/users/scottgriv/projects/7) tab inside this Repo to get a good understanding of where I'm currently at with the overall project. Bugs and Enhancements will also be tracked there as well. - ## Disclaimer + - The data provided by this application is sourced from the [USGS](https://www.usgs.gov/). - It's subject to revision, and for more information, please refer to their [official disclaimer](http://waterdata.usgs.gov/nwis/help/?provisional). - Software is provided as-is and no warranty is given about its usability. +## Project + +Please reference the [GitHub Project](https://github.com/users/scottgriv/projects/7) tab inside this Repo to get a good understanding of where I'm currently at with the overall project. Bugs and Enhancements will also be tracked there as well. + +## Configuration + +- Edit `config.py` to add your own USGS `API` (and other) information. + - [USGS API](https://waterservices.usgs.gov/rest/IV-Service.html) + - [USGS API Documentation](https://help.waterdata.usgs.gov/faq/automated-retrievals) +- Toggle `USE_DUMMY_DATA` to `True` in `config.py` to use dummy data instead of the `API`. + - This is useful for testing the application without making `API` calls. +- The float data plots are driven from a `.csv` file located in `static/data/river_charts.csv`. + - This file can be edited to add/remove float dates. + - The file is read in `views.py` and passed to the template as a `context` variable. + +## Deployment + +- The application is hosted [here](https://www.rivercharts.app) on [PythonAnywhere](https://www.pythonanywhere.com/). +- The application is deployed using a `WSGI` configuration file. + - [WSGI Configuration](https://docs.djangoproject.com/en/3.2/howto/deployment/wsgi/) +- First, make sure you adjust your `settings.py` file `ALLOWED_HOSTS` to include your deployment host. + - [Deploying Django](https://docs.djangoproject.com/en/3.2/howto/deployment/) +- Second, make sure you adjust your `settings.py` file `DEBUG` to `False` for production. + - [Django Settings](https://docs.djangoproject.com/en/3.2/ref/settings/) +- Finnaly, be sure to create a `.env` file where you host your application to store your sensitive information (excluded from this repository). + - [Python-Decouple](https://pypi.org/project/python-decouple/) + ## License + - **River Charts** is released under the terms of the **GNU General Public License, version 3 (GPLv3)**. The GPLv3 is a "copyleft" license, ensuring that derivatives of the software remain open source and under the GPL. - For more details and to understand all requirements and conditions, see the [LICENSE](LICENSE) file in this repository. ## Credit -**Author:** Scott Grivner
-**Email:** scott.grivner@gmail.com
+ +**Author:** [Scott Grivner](https://github.com/scottgriv)
+**Email:** [scott.grivner@gmail.com](mailto:scott.grivner@gmail.com)
**Website:** [scottgrivner.dev](https://www.scottgrivner.dev)
**Reference:** [Main Branch](https://github.com/scottgriv/River-Charts)
+ +--------------- +
diff --git a/VERSION b/VERSION deleted file mode 100644 index 7f20734..0000000 --- a/VERSION +++ /dev/null @@ -1 +0,0 @@ -1.0.1 \ No newline at end of file