|
|
Note
I will be using examples from my project River Charts throughout this README template.
- The description should be a short paragraph describing what your project is and what it does.
- This should be the first section after the badges.
- e.g. "A Python, Django, Plotly, and Pandas web application that visualizes river data pulled using an API from the United States Geological Survey (USGS)."
- Add screenshots of your project below the description and throughout the rest of the README as needed.
- This is optional, but highly recommended especially for Gold projects.
- Animations in the form of GIFs are also a great way to showcase your project.
Warning
Be sure to remove the .gitattributes file from this repository. It's used to classify this template repository as a Markdown file on GitHub only, and not needed.
- Features
- Background Story
- Definitions
- Getting Started
- Specific Project Sections
- What's Inside?
- Closing
- What's Next?
- Project
- Contributing
- Resources
- License -MIT -GNU -The Unlicense
- Credits
This section should contain a list of features that your project has.
The background story should be a short paragraph describing why you created the project and what inspired you to create it.
This section should contain a list of definitions for any terms that you use throughout your README.
- This is especially useful for technical terms that the reader may not be familiar with.
- e.g. Here are some definitions to help you understand the terminology used in this document:
- USGS: The United States Geological Survey. The USGS is a science organization that provides impartial information on the health of our ecosystems and environment, the natural hazards that threaten us, the natural resources we rely on, the impacts of climate and land-use change, and the core science systems that help us provide timely, relevant, and useable information.
- Gage Height: The height of the water surface above the gage datum (zero point). Gage height is often used interchangeably with the more general term, stage, although gage height is more appropriate when used with a gage reading. Stage is more appropriate when used with a recorded or calculated gage height.
This section should contain a list of steps to get your project up and running.
- You can break this section down into further subsections if you want (such as below: Dependencies, Configuration, Running Locally, Deployment, etc.).
- Otherwise, you can just include a list of steps to get your project up and running under Getting Started.
- This section should contain a list of dependencies for your project.
- This section should contain a list of steps to configure your project.
- This section should contain a list of steps to install your project.
- Utilize code blocks to show the commands needed to run your project.
- e.g.
- Clone this repository.
- Create a virtual environment:
python -m venv venv. - Install the dependencies.
- Run the application:
python manage.py runserver
- This section should contain a list of steps to deploy your project.
This section should contain a list of files and folders in your project and what each one does.
- Generally, you should only list the main files and folders in your project, not every single file.
- Use a tree diagram to show the relationship between files and folders:
- e.g.
├── 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. ├── 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.
There should be a number of sections here that correspond to important aspects of your project.
- Do not name this section "Specific Project Sections".
- e.g. "API", "Database", "Deployment", "Testing", etc.
This section should contain a short paragraph thanking the reader for taking the time to read your README.
This section should contain a list of features you plan to add to your project in the future.
e.g.
- Release v1.0.0 of River Charts.
- Enhance API call performance.
This section should contain a link to the project's website or a link to the project's repository.
This section should contain a list of steps for contributing to your project.
- You can also include a link to a separate
CONTRIBUTING.mdfile.- e.g. CONTRIBUTING.md
- Use a contributing generator like Contributing-Gen to create your
CONTRIBUTING.mdfile.
This section should contain a list of resources that you used to create your project.
Below are some external resources I found helpful when creating My Project:
- Python - An interpreted, high-level and general-purpose programming language.
- Plotly - A Python graphing library that makes interactive, publication-quality graphs online.
- Django - A high-level Python Web framework that encourages rapid development and clean, pragmatic design.
- Pandas - A fast, powerful, flexible and easy to use open source data analysis and manipulation tool, built on top of the Python programming language.
This section should contain the license for your project. It should include a link to your actual license file inside your repository, and a link to Choose an open source license for reference.
Important
Use the docs/LICENSE/ directory to pick amongst a few popular license files for your project.
You can also visit Choose an open source license to pick your own that's not included with this template.
If you don't include a LICENSE file, see what happens here.
For a zero restriction license, choose The Unlicense.
Warning
Be sure to remove the docs/LICENSE/ directory from this repository when you're done picking your license.
Be sure to include your LICENSE file in the root of your repository and change the link below to point towards it.
Examples:
This project is released under the terms of the MIT License, which permits use, modification, and distribution of the code, subject to the conditions outlined in the license.
- The MIT License provides certain freedoms while preserving rights of attribution to the original creators.
- For more details and to understand all requirements and conditions, see the LICENSE file in this repository.
This project is released under the terms of the GNU General Public License, version 3 (GNU GPLv3), which ensures that derivatives of the software remain open source.
- The GNU 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 file in this repository.
This project is released under the terms of The Unlicense, which allows you to use, modify, and distribute the code as you see fit.
- The Unlicense removes traditional copyright restrictions, giving you the freedom to use the code in any way you choose.
- For more details and to understand all requirements and conditions, see the LICENSE file in this repository.
Author: Scott Grivner
Email: scott.grivner@gmail.com
Website: scottgrivner.dev
Reference: Main Branch
