Adjust documentation

Author: amotl

README.md

@@ -1,37 +1,48 @@
-# grafana-client [![Github Actions Test](https://github.com/panodata/grafana-client/workflows/Test/badge.svg)](https://github.com/panodata/grafana-client/actions?query=workflow%3ATest) [![GitHub license](https://img.shields.io/github/license/panodata/grafana-client.svg?style=flat-square)](https://github.com/panodata/grafana-client/blob/master/LICENSE)  [![Codecov](https://img.shields.io/codecov/c/gh/panodata/grafana-client.svg?style=flat-square)](https://codecov.io/gh/panodata/grafana-client/)
+# grafana-client
 
-[![PyPI](https://img.shields.io/pypi/v/grafana-client.svg?style=flat-square)](https://pypi.org/project/grafana-api/) [![Conda](https://img.shields.io/conda/v/panodata/grafana-client.svg?style=flat-square)](https://anaconda.org/panodata/grafana-client)
+[![Tests](https://github.com/panodata/grafana-client/workflows/Test/badge.svg)](https://github.com/panodata/grafana-client/actions?query=workflow%3ATest)
+[![Test coverage](https://img.shields.io/codecov/c/gh/panodata/grafana-client.svg?style=flat-square)](https://codecov.io/gh/panodata/grafana-client/)
+[![License](https://img.shields.io/github/license/panodata/grafana-client.svg?style=flat-square)](https://github.com/panodata/grafana-client/blob/main/LICENSE) 
 
-## What is this library for?
+[![PyPI](https://img.shields.io/pypi/v/grafana-client.svg?style=flat-square)](https://pypi.org/project/grafana-client/)
+[![Python versions](https://img.shields.io/pypi/pyversions/grafana-client.svg?style=flat-square)](https://pypi.org/project/grafana-client/)
+[![Status](https://img.shields.io/pypi/status/grafana-client.svg?style=flat-square)](https://pypi.org/project/grafana-client/)
+<!-- [![Conda](https://img.shields.io/conda/v/panodata/grafana-client.svg?style=flat-square)](https://anaconda.org/panodata/grafana-client) -->
 
-Yet another Grafana API library for Python. Support Python 3 only.
+## About
 
-## Requirements
-
-You need Python 3 and only the `requests` library installed.
+A client library for the Grafana HTTP API, written in Python.
 
 ## History
 
-The library was originally conceived by Andrew Prokhorenkov at https://github.com/m0nhawk/grafana_api.
-Thank you very much for your efforts!
+The library was originally conceived by [Andrew Prokhorenkov] and contributors
+as [grafana_api]. Thank you very much for your efforts!
+
+At [future maintenance of `grafana_api`], we discussed the need for a fork
+because the repository stopped receiving updates since more than a year.
+
+While forking it, we renamed the package to `grafana-client` and slightly
+trimmed the module namespace.
+
 
-## Quick start
 
-Install the pip package:
+## Getting started
+
+Install the package from PyPI.
 
 ```
-pip install -U grafana-client
+pip install grafana-client --upgrade
 ```
 
-And then connect to your Grafana API endpoint:
+Connect to your Grafana API endpoint using the `GrafanaFace` interface.
 
 ```python
 from grafana_client.grafana_face import GrafanaFace
 
-grafana = GrafanaFace(auth='abcde....', host='api.my-grafana-host.com')
+grafana = GrafanaFace(auth='abcde....', host='grafana.example.org')
 
 # Create user
-user = grafana.admin.create_user({"name": "User", "email": "user@domain.com", "login": "user", "password": "userpassword", "OrgId": 1})
+user = grafana.admin.create_user({"name": "User", "email": "user@example.org", "login": "user", "password": "userpassword", "OrgId": 1})
 
 # Change user password
 user = grafana.admin.change_user_password(2, "newpassword")
@@ -58,29 +69,35 @@ grafana.organization.create_organization({"name":"new_organization"})
 
 ## Authentication
 
-There are two ways to autheticate to grafana api. Either use api token or basic auth.
+There are two ways to authenticate to the Grafana API. Either use an API token,
+or HTTP basic auth.
+
+To use the admin API, you need to use HTTP basic auth, as stated at the
+[Grafana Admin API documentation].
 
-To use admin API you need to use basic auth [as stated here](https://grafana.com/docs/grafana/latest/http_api/admin/)
 
 ```python
-# Use basic authentication:
+from grafana_client.grafana_face import GrafanaFace
 
+# Use HTTP basic authentication
 grafana = GrafanaFace(
-          auth=("username","password"),
-          host='api.my-grafana-host.com'
-          )
+    auth=("username", "password"),
+    host='grafana.example.org'
+)
 
-# Use token
+# Use Grafana API token
 grafana = GrafanaFace(
-          auth='abcdetoken...',
-          host='api.my-grafana-host.com'
-          )
+    auth='eyJrIjoiWHg...dGJpZCI6MX0=',
+    host='grafana.example.org'
+)
 ```
 
 
-## Status of REST API realization
+## Status
+
+This table outlines which parts of Grafana's HTTP API are covered by
+`grafana-client`, see also [Grafana HTTP API reference].
 
-Work on API implementation still in progress.
 
 | API | Status |
 |---|---|
@@ -107,27 +124,34 @@ Work on API implementation still in progress.
 ## Software tests
 
 ```shell
-pip install pytest
-pytest test
+python setup.py test
 ```
 
-## Release
 
-```shell
-pip install pep517 twine
-python -m pep517.build --source --binary --out-dir dist/ .
-twine upload --repository=testpypi dist/*
-```
+## Acknowledgements
+
+Thanks to all the [contributors] who helped to co-create and conceive this
+software in one way or another. You know who you are.
 
-## Issue tracker
 
-Please report any bugs and enhancement ideas using the `grafana-client` issue tracker:
+## Contributing
 
-  https://github.com/panodata/grafana-client/issues
+Any kind of contribution and feedback are very much welcome! Just create an
+issue or submit a patch if you think we should include a new feature, or to 
+report or fix a bug.
+
+The issue tracker URL is: https://github.com/panodata/grafana-client/issues
 
-Feel free to also ask questions on the tracker.
 
 ## License
 
-`grafana-client` is licensed under the terms of the MIT License (see the file
-[LICENSE](LICENSE)).
+`grafana-client` is licensed under the terms of the MIT License, see [LICENSE] file.
+
+
+[Andrew Prokhorenkov]: https://github.com/m0nhawk/grafana_api
+[contributors]: https://github.com/panodata/grafana-client/graphs/contributors
+[future maintenance of `grafana_api`]: https://github.com/m0nhawk/grafana_api/issues/88
+[grafana_api]: https://github.com/m0nhawk/grafana_api
+[Grafana Admin API documentation]: https://grafana.com/docs/grafana/latest/http_api/admin/
+[Grafana HTTP API reference]: https://grafana.com/docs/grafana/latest/http_api/
+[LICENSE]: https://github.com/panodata/grafana-client/blob/main/LICENSE

docs/backlog.md

@@ -2,3 +2,5 @@
 
 - `python -m pep517.build --source --binary --out-dir dist/ .`
   pep517.build is deprecated. Consider switching to https://pypi.org/project/build/
+- Format code with `black` and `isort``
+- Clarify *"To use admin API you need to use basic auth"*, see README.

setup.cfg

@@ -1,7 +1,7 @@
 [metadata]
 name = grafana-client
-friendly_name = Python Grafana API
-description = Yet another Python library for Grafana API
+friendly_name = Grafana client
+description = A client library for the Grafana HTTP API, written in Python
 long_description = file: README.md
 long_description_content_type = text/markdown
 license = MIT
@@ -26,7 +26,7 @@ classifiers =
     Topic :: Software Development
     Topic :: Software Development :: Libraries
     Topic :: Software Development :: Libraries :: Python Modules
-keywords = grafana api
+keywords = grafana http api grafana-client grafana-api automation
 
 [options]
 use_scm_version = True