Basic first paragraph (#116)

* Basic first paragraph

* open in new tab didn't render

* code format

* template update

---------

Co-authored-by: malmans2 <[email protected]>

Author: EddyCMWF

.cruft.json

@@ -1,6 +1,6 @@
 {
   "template": "https://github.com/ecmwf-projects/cookiecutter-conda-package",
-  "commit": "10b34190df391ff68b327ed9a330c412769fc474",
+  "commit": "3b3ac4ab7d8039431b21fec307a590e995c83dfa",
   "checkout": null,
   "context": {
     "cookiecutter": {

.github/workflows/on-push.yml

@@ -242,6 +242,6 @@ jobs:
       with:
         name: distribution
         path: dist
-    - uses: pypa/gh-action-pypi-publish@v1.10.3
+    - uses: pypa/gh-action-pypi-publish@v1.12.2
       with:
         verbose: true

.gitignore

@@ -2,6 +2,7 @@
 version.py
 
 # Sphinx automatic generation of API
+docs/README.md
 docs/_api/
 
 # Combined environments

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
   - id: blackdoc
     additional_dependencies: [black==23.11.0]
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.7.1
+  rev: v0.7.3
   hooks:
   - id: ruff
     args: [--fix, --show-fixes]
@@ -34,6 +34,6 @@ repos:
   - id: pretty-format-toml
     args: [--autofix]
 - repo: https://github.com/gitleaks/gitleaks
-  rev: v8.21.1
+  rev: v8.21.2
   hooks:
   - id: gitleaks

Makefile

@@ -29,7 +29,7 @@ template-update:
 	pre-commit run --all-files cruft -c .pre-commit-config-cruft.yaml
 
 docs-build:
-	cd docs && rm -fr _api && make clean && make html
+	cp README.md docs/. && cd docs && rm -fr _api && make clean && make html
 
 # DO NOT EDIT ABOVE THIS LINE, ADD COMMANDS BELOW
 

README.md

@@ -2,7 +2,9 @@
 
 CADS API Python client
 
-Documentation: https://ecmwf-projects.github.io/cads-api-client/
+Technical documentation: https://ecmwf-projects.github.io/cads-api-client/
+
+## Configuration
 
 The `ApiClient` requires the `url` to the API root and a valid API `key`. You can also set the `CADS_API_URL` and `CADS_API_KEY` environment variables, or use a configuration file. The configuration file must be located at `~/.cads-api-client.json`, or at the path specified by the `CADS_API_RC` environment variable.
 

docs/index.md

@@ -1,11 +1,16 @@
-# Welcome to cads_api_client's documentation!
+# Welcome to cads-api-client's documentation!
 
-CADS API Python client.
+The `cads-api-client` provides programmatic access to the CDS, ADS and EWDS data catalogues.
+These pages provide technical documentation for advanced users and/or developers.
+For a more detailed and user friendly documentation please refer to the
+[Climate Data Store (CDS) User Guide](https://confluence.ecmwf.int/x/vTRtD) in the Copernicus
+Knowledge Base.
 
 ```{toctree}
 :caption: 'Contents:'
 :maxdepth: 2
 
+README.md
 API Reference <_api/cads_api_client/index>
 ```