From d1b4f6cf946d958e7352ac10925409cbc5e08911 Mon Sep 17 00:00:00 2001
From: Jon Hadfield <jon@lessknown.co.uk>
Date: Tue, 24 Jun 2025 16:27:39 +0100
Subject: [PATCH] Improve documentation

---
 README.md      | 35 ++++++++++++++++++++++++++++++-----
 docs/index.rst |  4 +++-
 docs/usage.rst | 14 ++++++++++++++
 3 files changed, 47 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 0f70776..a7c24b1 100644
--- a/README.md
+++ b/README.md
@@ -3,10 +3,20 @@ python-hosts
 [![codecov](https://codecov.io/gh/jonhadfield/python-hosts/branch/devel/graph/badge.svg)](https://codecov.io/gh/jonhadfield/python-hosts) [![Docs](https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat)](http://python-hosts.readthedocs.org/en/latest/)
 
 
-This is a python library for managing a hosts file.
-It enables you to add and remove entries, or import them from a file or URL.
-Utility functions have been streamlined for easier maintenance.
-It remains compatible with Python 2.7 as well as modern Python 3 releases.
+`python-hosts` is a small Python library for reading and writing hosts files.
+It provides a simple API for adding or removing entries as well as importing
+records from another file or a remote URL.  The package has no heavy
+dependencies and works on Linux, macOS and Windows.
+
+It remains compatible with Python 2.7 in addition to modern Python 3 releases.
+
+Features
+--------
+* Add, remove or merge host entries programmatically.
+* Import entries from a plain text file or from a URL.
+* Works across platforms by automatically selecting the correct hosts file
+  location.
+* Python 2.7 and Python 3.5+ support.
 
 Documentation
 -------------
@@ -20,7 +30,7 @@ Installation
 pip install python-hosts
 
 Example usage
-------------
+-------------
 Adding an entry to a hosts file
 
     from python_hosts import Hosts, HostsEntry
@@ -36,6 +46,13 @@ Importing a list of host entries by URL
     hosts.import_url(url='https://gist.githubusercontent.com/jonhadfield/5b6cdf853ef629f9b187345d89157280/raw/ddfa4a069fb12bf3c1f285249d44922aeb75db3f/hosts')
     hosts.write()
 
+Importing entries from another file
+
+    from python_hosts import Hosts
+    hosts = Hosts(path='hosts_test')
+    hosts.import_file(import_file_path='other_hosts')
+    hosts.write()
+
 CLI
 ---
 A command line client using python-hosts can be found here: https://github.com/jonhadfield/hostman
@@ -46,6 +63,14 @@ Requirements
 
 Tested on Python 2.7 and Python 3.5+, including PyPy variants
 
+Running tests
+-------------
+Install the development requirements and run::
+
+    pip install -r test-requirements.txt
+    pytest
+
+
 
 License
 -------
diff --git a/docs/index.rst b/docs/index.rst
index 06de160..5d1ee7c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -2,7 +2,8 @@
 python hosts
 ============
 
-A python library for managing a hosts file.
+A Python library for managing hosts files. It can add or remove entries and
+import records from other files or remote URLs.
 
 
 Getting started
@@ -13,6 +14,7 @@ Getting started
 
    installation
    usage
+   ../CHANGELOG
 
 
 API
diff --git a/docs/usage.rst b/docs/usage.rst
index 5df4b03..88b5294 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -21,3 +21,17 @@ Usage
 **Write entries**::
 
  my_hosts.write()
+
+**Import entries from a URL**::
+
+ from python_hosts import Hosts
+ my_hosts = Hosts(path='hosts_test')
+ my_hosts.import_url(url='https://example.com/hosts')
+ my_hosts.write()
+
+**Import entries from another file**::
+
+ from python_hosts import Hosts
+ my_hosts = Hosts(path='hosts_test')
+ my_hosts.import_file(import_file_path='other_hosts')
+ my_hosts.write()