Rework and deduplicate the Python WireMock documentation

CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing to Python WireMock
+
+[![a](https://img.shields.io/badge/slack-%23wiremock%2Fpython-brightgreen?style=flat&logo=slack)](https://slack.wiremock.org/)
+
+## Get Started
+
+1. Join us ion the `#wiremock-python` channel on the [WireMock Slack](https://slack.wiremock.org/)
+2. Check out the GitHub issues!
+
+## Pull Requests
+
+General Rules:
+
+- All Tests must pass
+- Coverage shouldn't decrease
+- All Pull Requests should be rebased against master **before** submitting the PR.
+
+## Development
+
+Setup the project using poetry.
+
+`poetry install`

README.md

@@ -1,12 +1,13 @@
-# Python WireMock Admin API Client
+# Python WireMock
 
 <p align="center">
     <a href="https://wiremock.org/docs/solutions/python/" target="_blank">
         <img width="512px" src="docs/images/python-wiremock-horizontal.png" alt="WireMock Logo"/>
     </a>
 </p>
 
-Python Wiremock is an HTTP client that allows users to interact with a Wiremock instance from within a Python project.
+Python WireMock is a library that allows users to interact with a WireMock instance from within a Python project.
+Full documentation can be found at [wiremock.readthedocs.org](http://wiremock.readthedocs.org/).
 
 [![a](https://img.shields.io/badge/slack-%23wiremock%2Fpython-brightgreen?style=flat&logo=slack)](https://slack.wiremock.org/)
 [![Docs](https://img.shields.io/badge/docs-latest-brightgreen.svg)](http://wiremock.readthedocs.org/)
@@ -20,91 +21,22 @@ FIXME: Reporting is dead: https://github.com/wiremock/python-wiremock/issues/74
 
 WireMock can run in unit tests, as a standalone process or a container. Key features include:
 
+- [Testcontainers Python](https://github.com/testcontainers/testcontainers-python) module to easily start WireMock server for your tests
+- REST API Client for a standalone WireMock Java server
 - Supports most of the major [Wiremock](https://wiremock.org/docs) features (more on their way soon)
-- Support for [testcontainers-python](https://github.com/testcontainers/testcontainers-python) to easily start wiremock server for your tests
-- Support for standalone wiremock JAVA sever
 
-## Install as Dependency
+## References
 
-To install:
-
-    `pip install wiremock`
-
-To install with testing dependencies:
-
-    `pip install wiremock[testing]`
-
-To install via Poetry:
-
-    `poetry add --extras=testing wiremock`
-
-## Quick Start
-
-The preferred way of using WireMock to mock your services is by using the provided `WireMockContainer` [testcontainers-python](https://github.com/testcontainers/testcontainers-python).
-
-```python
-import pytest
-
-from wiremock.testing.testcontainer import wiremock_container
-
-@pytest.fixture(scope="session") # (1)
-def wm_server():
-    with wiremock_container(secure=False) as wm:
-
-        Config.base_url = wm.get_url("__admin") # (2)
-
-        Mappings.create_mapping(
-            Mapping(
-                request=MappingRequest(method=HttpMethods.GET, url="/hello"),
-                response=MappingResponse(status=200, body="hello"),
-                persistent=False,
-            )
-        ) # (3)
-        yield wm
-
-
-def test_get_hello_world(wm_server): # (4)
-
-    resp1 = requests.get(wm_server.get_url("/hello"), verify=False)
-
-    assert resp1.status_code == 200
-    assert resp1.content == b"hello"
-```
-
-1. Create a pytest fixture to manage the container life-cycle. use fixture `scope` to control how often the container is created
-
-2. Set the wiremock sdk config url to the url exposed by the container
-
-3. Create response and request mappings using the Admin SDK.
-
-4. Use the `wm_server` fixture in your tests and make requests against the mock server.
-
-You can read more about Testcontainers support in python-wiremock [here](docs/testcontainers.md).
+- [Quickstart Guide](./docs/quickstart.md)
+- [Installation](./docs/install.md)
+- [Full documentation](http://wiremock.readthedocs.org/)
 
 ## Examples
 
 There are several example projects included to demonstrate the different ways that wiremock can be used to mock
 services in your tests and systems. The example test modules demonstrate different strategies for testing against
 the same "product service" and act as a good demonstration of real world applications to help you get started.
 
-- [Python Testcontainers](example/tests/test_testcontainers.py)
+- [Testcontainers Python](example/tests/test_testcontainers.py)
 
 - [Standalone Java Server Version](example/tests/test_java_server.py)
-
-## Documentation
-
-wiremock documentation can be found at http://wiremock.readthedocs.org/
-
-## Pull Requests
-
-General Rules:
-
-- All Tests must pass
-- Coverage shouldn't decrease
-- All Pull Requests should be rebased against master **before** submitting the PR.
-
-## Development
-
-Setup the project using poetry.
-
-`poetry install`

docs/api-client.md

@@ -0,0 +1,73 @@
+Using with a Standalone WireMock
+===========
+
+An example app:
+
+```python
+from wiremock.constants import Config
+from wiremock.client import *
+
+Config.base_url = 'https://mockserver.example.com/__admin/'
+# Optionally set a custom cert path:
+# Config.requests_cert = ... (See requests documentation)
+# Optionally disable cert verification
+# Config.requests_verify = False
+
+mapping = Mapping(
+    priority=100,
+    request=MappingRequest(
+        method=HttpMethods.GET,
+        url='/hello'
+    ),
+    response=MappingResponse(
+        status=200,
+        body='hi'
+    ),
+    persistent=False,
+)
+
+mapping = Mappings.create_mapping(mapping=mapping)
+
+all_mappings = Mappings.retrieve_all_mappings()
+```
+
+### Starting WireMock server with a context manager
+
+```python
+from wiremock.constants import Config
+from wiremock.client import *
+from wiremock.server.server import WireMockServer
+
+with WireMockServer() as wm:
+    Config.base_url = 'http://localhost:{}/__admin'.format(wm.port)
+    Mappings.create_mapping(...)  # Set up stubs
+    requests.get(...)             # Make API calls
+```
+
+### Starting WireMock server in a unittest.TestCase
+
+```python
+
+class MyTestClassBase(TestCase):
+    @classmethod
+    def setUpClass(cls):
+        wm = self.wiremock_server = WireMockServer()
+        wm.start()
+        Config.base_url = 'http://localhost:{}/__admin'.format(wm.port)
+
+    @classmethod
+    def tearDownClass(cls):
+        self.wiremock_server.stop()
+```
+
+### Customizing the path to java
+
+```python
+WireMockServer(java_path='/path/to/my/java')
+```
+
+### Customizing the WireMock server JAR file:
+
+```python
+WireMockServer(jar_path='/my/secret/location/wiremock-standalone-2.35.0.jar')
+```

docs/changelog.md

@@ -3,6 +3,11 @@ ChangeLog
 
 Changes to the library are recorded here.
 
+Newer version
+------
+
+See [GitHub Releases](https://github.com/wiremock/python-wiremock/releases)
+
 v2.4.0
 ------
 

docs/index.md

@@ -1,46 +1,42 @@
-Python client for WireMock standalone Admin API 
-=====
+# Python WireMock
 
-This library provides a HTTP client to the WireMock standalone server's
-admin API.
+Python WireMock is an HTTP client that allows users to interact with a WireMock instance from within a Python project.
 
-Links
-=====
+[![a](https://img.shields.io/badge/slack-%23wiremock%2Fpython-brightgreen?style=flat&logo=slack)](https://slack.wiremock.org/)
 
-- WireMock Standalone: <https://wiremock.org/docs/standalone/>
-- Documentation: <https://wiremock.readthedocs.io/en/latest/>
-- Official Repository:
-    <https://github.com/wiremock/python-wiremock.git>
-- Package: TODO
+## Key Features
 
-Requirements
-============
+WireMock can run in unit tests, as a standalone process or a container, or in the cloud.
+Python WireMock enables all these usage modes.
+Key features include:
 
-wiremock is known to support Python 3.7.
+- [Testcontainers Python](https://github.com/testcontainers/testcontainers-python) module to easily start WireMock server for your tests
+- REST API Client for a standalone WireMock Java server
+- Supports most of the major [Wiremock](https://wiremock.org/docs) features (more on their way soon)
 
-Download
-========
+## Documentation
 
-PyPI: TODO
+- [Quickstart](./quickstart.md)
+- [Installation](./install.md)
+- [Testconatiners module](./testcontainers.md)
+- [Using with standalone WireMock](./api-client.md)
 
-```bash
-$ pip install wiremock
-```
+## Links
 
-Source: <https://github.com/wiremock/python-wiremock.git>
+- WireMock Standalone: <https://wiremock.org/docs/standalone/>
+- Documentation: <https://wiremock.readthedocs.io/en/latest/>
+- Official Repository: <https://github.com/wiremock/python-wiremock.git>
+- Package: <https://pypi.org/project/wiremock>
 
-```bash
-$ git clone TODO
-$ poetry install
-```
+<!--
 
 Contents
 ========
 
 Indices and tables
 ------------------
 
-<!--
+
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`

docs/install.md

@@ -0,0 +1,32 @@
+# Installation
+
+## Requirements
+
+Python WireMock is known to support Python 3.7 or above.
+
+## Pip
+
+To install:
+
+    `pip install wiremock`
+
+To install with testing dependencies:
+
+    `pip install wiremock[testing]`
+
+## Poetry
+
+To install via Poetry:
+
+    `poetry add wiremock`
+
+Or:
+
+```bash
+git clone [TODO](https://github.com/wiremock/python-wiremock.git)
+poetry install
+```
+
+To install with testing dependencies:
+
+    `poetry add --extras=testing wiremock`