improve docs (#34)

* change Github to GitHub * change PyPi to PyPI * update readme * Prefer CodeQL badge name instead of codeql
kiraware · Jul 12, 2024 · 2ddd40c · 2ddd40c
1 parent bad6325
commit 2ddd40c
Show file tree

Hide file tree

Showing 4 changed files with 89 additions and 48 deletions.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -29,7 +29,7 @@ jobs:
       - name: Mint token
         id: mint
         uses: tschm/token-mint-action@v1.0.3
-      - name: Publish to PyPi
+      - name: Publish to PyPI
         env:
           PYPI_TOKEN: ${{ steps.mint.outputs.api-token }}
         run: |

diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 # PyBMKG
 
 [![CI](https://github.com/kiraware/PyBMKG/workflows/ci/badge.svg)](https://github.com/kiraware/PyBMKG/actions/workflows/ci.yml)
-[![CodeQL](https://github.com/kiraware/PyBMKG/workflows/codeql/badge.svg)](https://github.com/kiraware/PyBMKG/actions/workflows/codeql.yml)
+[![CodeQL](https://github.com/kiraware/PyBMKG/workflows/CodeQL/badge.svg)](https://github.com/kiraware/PyBMKG/actions/workflows/codeql.yml)
 [![Docs](https://readthedocs.org/projects/pybmkg/badge/?version=latest)](https://pybmkg.readthedocs.io/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/kiraware/PyBMKG/graph/badge.svg?token=MN6AXAHO0P)](https://codecov.io/gh/kiraware/PyBMKG)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
@@ -10,35 +10,53 @@
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![pypi](https://img.shields.io/pypi/v/PyBMKG.svg)](https://pypi.org/project/PyBMKG/)
 [![python](https://img.shields.io/pypi/pyversions/PyBMKG.svg)](https://pypi.org/project/PyBMKG/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/license/mit/)
-
-This is documentation for the `PyBMKG` project that
-is an asynchronous api wrapper written in Python for
-[open data](https://data.bmkg.go.id/) on weather
-forecasts and latest earthquakes in Indonesia served
-by Meteorology, Climatology and Geophysics Agency
-([BMKG](https://bmkg.go.id/)).
-
-PyBMKG was created as a wrapper to handle API requests
-BMKG open data asynchronously. This is because the
-available API does not follow API standards in general,
-therefore a wrapper was created which is expected to
-make it easier to use the BMKG open data API with Python.
-
-We use the third party library [aiohttp](https://docs.aiohttp.org/en/stable/)
-for asynchronous client requests and it has been tested
-to work well using the [asyncio](https://docs.python.org/3/library/asyncio.html)
-library. Also it use [dataclass](https://docs.python.org/3/library/dataclasses.html)
-as the schema.
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/license/MIT)
+
+PyBMKG is an asynchronous Python API wrapper designed to harness the power of BMKG's open data
+on weather forecasts and earthquake information in Indonesia. Powered by the Meteorology,
+Climatology, and Geophysics Agency ([BMKG](https://bmkg.go.id/)), this project aims to streamline
+access to crucial meteorological and seismic data.
+
+## Key Features
+
+- **Asynchronous Operations:** Utilizes `asyncio` and `aiohttp` for efficient API requests.
+- **Data Schema:** Built with Python's `dataclass` for clear and structured data representation.
+- **Comprehensive Documentation:** Explore detailed [documentation](https://pybmkg.readthedocs.io/en/latest/) for seamless integration and usage.
+
+## Installation
+
+```bash
+pip install PyBMKG
+```
+
+## Usage
+
+```python
+import asyncio
+
+from bmkg import BMKG
+from bmkg.enums import Province
+
+async def main():
+    async with BMKG() as bmkg:
+        weather_forecast = await bmkg.weather_forecast.get_weather_forecast(Province.ACEH)
+        latest_earthquake = await bmkg.earthquake.get_latest_earthquake()
+
+        print(f'Weather Forecast: {weather_forecast}')
+        print(f'Latest Earthquakes: {latest_earthquake}')
+
+asyncio.run(main())
+```
 
 ## Docs
 
 You can start reading the documentation [here](https://pybmkg.readthedocs.io/en/latest/).
 
 ## Contributing
 
-Glad to hear you want to contribute to PyBMKG. Please see
-[contributing guidelines](https://pybmkg.readthedocs.io/en/latest/how-to-guides/#contributing).
+We welcome contributions to enhance PyBMKG! Please review our
+[contributing guidelines](https://pybmkg.readthedocs.io/en/latest/how-to-guides/#contributing)
+before getting started.
 
 ## Acknowledgements
 

diff --git a/docs/how-to-guides.md b/docs/how-to-guides.md
@@ -128,8 +128,8 @@ poetry run mkdocs serve
 
 ### Releasing
 
-We use the GitHub workflow to automatically release to PyPi when we
-release to Github. The special environment for people who have access
-to the workflow is in the Github environment with the name `production`.
+We use the GitHub workflow to automatically release to PyPI when we
+release to GitHub. The special environment for people who have access
+to the workflow is in the GitHub environment with the name `production`.
 Each release tag must be the same as `version` in `pyproject.toml` in
 the `tool.poetry` section.
diff --git a/docs/index.md b/docs/index.md
@@ -1,7 +1,7 @@
 # PyBMKG
 
 [![CI](https://github.com/kiraware/PyBMKG/workflows/ci/badge.svg)](https://github.com/kiraware/PyBMKG/actions/workflows/ci.yml)
-[![CodeQL](https://github.com/kiraware/PyBMKG/workflows/codeql/badge.svg)](https://github.com/kiraware/PyBMKG/actions/workflows/codeql.yml)
+[![CodeQL](https://github.com/kiraware/PyBMKG/workflows/CodeQL/badge.svg)](https://github.com/kiraware/PyBMKG/actions/workflows/codeql.yml)
 [![Docs](https://readthedocs.org/projects/pybmkg/badge/?version=latest)](https://pybmkg.readthedocs.io/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/kiraware/PyBMKG/graph/badge.svg?token=MN6AXAHO0P)](https://codecov.io/gh/kiraware/PyBMKG)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
@@ -10,26 +10,43 @@
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![pypi](https://img.shields.io/pypi/v/PyBMKG.svg)](https://pypi.org/project/PyBMKG/)
 [![python](https://img.shields.io/pypi/pyversions/PyBMKG.svg)](https://pypi.org/project/PyBMKG/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/license/mit/)
-
-This is documentation for the `PyBMKG` project that
-is an asynchronous api wrapper written in Python for
-[open data](https://data.bmkg.go.id/) on weather
-forecasts and latest earthquakes in Indonesia served
-by Meteorology, Climatology and Geophysics Agency
-([BMKG](https://bmkg.go.id/)).
-
-PyBMKG was created as a wrapper to handle API requests
-BMKG open data asynchronously. This is because the
-available API does not follow API standards in general,
-therefore a wrapper was created which is expected to
-make it easier to use the BMKG open data API with Python.
-
-We use the third party library [aiohttp](https://docs.aiohttp.org/en/stable/)
-for asynchronous client requests and it has been tested
-to work well using the [asyncio](https://docs.python.org/3/library/asyncio.html)
-library. Also it use [dataclass](https://docs.python.org/3/library/dataclasses.html)
-as the schema.
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/license/MIT)
+
+PyBMKG is an asynchronous Python API wrapper designed to harness the power of BMKG's open data
+on weather forecasts and earthquake information in Indonesia. Powered by the Meteorology,
+Climatology, and Geophysics Agency ([BMKG](https://bmkg.go.id/)), this project aims to streamline
+access to crucial meteorological and seismic data.
+
+## Key Features
+
+- **Asynchronous Operations:** Utilizes `asyncio` and `aiohttp` for efficient API requests.
+- **Data Schema:** Built with Python's `dataclass` for clear and structured data representation.
+- **Comprehensive Documentation:** Explore detailed [documentation](https://pybmkg.readthedocs.io/en/latest/) for seamless integration and usage.
+
+## Installation
+
+```bash
+pip install PyBMKG
+```
+
+## Usage
+
+```python
+import asyncio
+
+from bmkg import BMKG
+from bmkg.enums import Province
+
+async def main():
+    async with BMKG() as bmkg:
+        weather_forecast = await bmkg.weather_forecast.get_weather_forecast(Province.ACEH)
+        latest_earthquake = await bmkg.earthquake.get_latest_earthquake()
+
+        print(f'Weather Forecast: {weather_forecast}')
+        print(f'Latest Earthquakes: {latest_earthquake}')
+
+asyncio.run(main())
+```
 
 ## Table Of Contents
 
@@ -40,6 +57,12 @@ following links:
 2. [How-To Guides](how-to-guides.md)
 3. [Reference](reference/api.md)
 
+## Contributing
+
+We welcome contributions to enhance PyBMKG! Please review our
+[contributing guidelines](how-to-guides.md/#contributing)
+before getting started.
+
 ## Acknowledgements
 
 We would like to thank the Meteorology, Climatology