🔥 Remove duplicated docs on installation; improve docs.

Author: rafalkrupinski

.config/mkdocs.yaml

@@ -17,8 +17,7 @@ exclude_docs: |
 nav:
 - index.md
 - Usage:
-  - Installation: usage/installation.md
-  - usage/client.md
+  - Client class: usage/client.md
   - usage/operation.md
   - usage/auth.md
 - API reference: reference/api.md

Readme.md

@@ -2,44 +2,20 @@
 
 [![test](https://github.com/python-lapidary/lapidary/actions/workflows/test_publish.yaml/badge.svg)](https://github.com/python-lapidary/lapidary/actions/workflows/test_publish.yaml)
 
-Python DSL for Web API clients.
+Python Helper for Web API clients.
 
 ## Why
 
-Web API clients follow a relatively small set of patterns and implementing them is rather repetitive task. Encapsulating these patterns in form of a DSL library frees its users from coding the same patterns over and over again.
+Web API clients follow a relatively small set of patterns and implementing them is rather repetitive task.
+Prepare request, make the call, handle response status, deserialize the body
+Typical examples show how to use `request.get()` or similar method, but this is an anti-pattern. These calls should be encapsulated as module functions or methods.
 
 ## How
 
-Lapidary is an internal (in-python) DSL made of decorators and annotations, that can be used to describe Web APIs similarly to OpenAPI.
-([lapidary-render](https://github.com/python-lapidary/lapidary-render/) can convert a large subset of OpenAPI 3.0 to Lapidary).
-
-At runtime, the library interprets user-provided function declarations (without bodies), and makes them behave as declared. If a function accepts parameter of type `X` and returns `Y`, Lapidary will try to convert `X` to HTTP request and the response to `Y`.
-
-### Example:
-
-```python
-class CatClient(ClientBase):
-    """This class is a working API client"""
-
-    def __init__(self):
-        super().__init__(
-            base_url='https://example.com/api',
-        )
-
-    @get('/cat')
-    async def list_cats(self: Self) -> Annotated[
-        tuple[list[Cat], CatListMeta],
-        Responses({
-            '2XX': Response(
-                Body({
-                    'application/json': list[Cat],
-                }),
-                CatListMeta
-            ),
-        })
-    ]:
-       pass
-
-client = CatClient()
-cats_body, cats_meta = await client.list_cats()
-```
+Lapidary is a library that provides decorators and annotations for describing Web APIs in a way similar to OpenAPI.
+In fact [lapidary render](https://github.com/python-lapidary/lapidary-render/) can convert much of OpenAPI 3.0 to Lapidary code.
+
+At runtime, the library interprets user-provided function declarations and makes them behave as specified.
+If a function accepts parameter of type `X` and returns `Y`, Lapidary will try to convert `X` to HTTP request and the response back to `Y`.
+
+Check the [example](https://python-lapidary.github.io/lapidary/#usage)

docs/index.md

@@ -1,12 +1,14 @@
 # Lapidary
 
-Python DSL for Web API clients.
+Python helper for creating Web API clients.
 
 ## Features
 
 - [x] Write Web API clients declaratively
-- [x] Use pydantic models for JSON data
-- [ ] Compatibility with OpenAPI 3.0 and 3.1
+- [x] Use [pydantic](https://docs.pydantic.dev/latest/) models for JSON data
+- [x] Compatibility with [OpenAPI](https://www.openapis.org/)
+    - [x] 3.0
+    - [ ] 3.1 (Planned)
 
 ## Installation
 
@@ -57,9 +59,10 @@ class CatClient(ClientBase):
         })),
     })]:
         pass
+```
 
-# User code
-
+User code
+```python
 async def main():
     client = CatClient()
     cat = await client.cat_get(id=7)
@@ -68,6 +71,9 @@ async def main():
 See [this test file](https://github.com/python-lapidary/lapidary/blob/develop/tests/test_client.py) for a working
 example.
 
-[Full documentation](https://lapidary.dev)
+Also check [clients](https://github.com/orgs/lapidary-library/repositories) generated with Lapidary Render.
+
+
+## Prior work
 
-Also check the [library of clients](https://github.com/orgs/lapidary-library/repositories).
+[Uplink 📡](https://uplink.prkumar.dev/) - more mature and full-featured but not designed with OpenAPI compatibility in mind.

docs/usage/installation.md

@@ -22,7 +22,7 @@ class CatClient(ClientBase):
 
 !!! note
 
-    In the examples below, methods are depicted as standalone functions, with the encapsulating class structure omitted.
+    In the examples below, methods are written as top-level functions, while in real code you would write them as methods.
 
 ```python
 @get('/cats')  # method and path