From d54bedf7421f3674eb0db37a60c8d5f3d3d5ff55 Mon Sep 17 00:00:00 2001 From: Kira <117554978+kiraware@users.noreply.github.com> Date: Fri, 12 Jul 2024 21:26:42 +0800 Subject: [PATCH] improve docs * change Github to GitHub * change PyPi to PyPI * update readme * Prefer CodeQL badge name instead of codeql --- .github/workflows/release.yml | 2 +- README.md | 64 +++++++++++++++++++++------------- docs/how-to-guides.md | 6 ++-- docs/index.md | 65 ++++++++++++++++++++++++----------- 4 files changed, 89 insertions(+), 48 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index f73ab13..4434d9c 100644 --- 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 index f217731..cfb0d1b 100644 --- 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,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()) +``` ## Docs @@ -37,8 +54,9 @@ You can start reading the documentation [here](https://pybmkg.readthedocs.io/en/ ## 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 index 03610ba..61a5b7d 100644 --- 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 index 89c2a2b..901f38e 100644 --- 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