docs: overall tidy up of README, docstrings + Sphinx docs

CONTRIBUTING.md

@@ -6,13 +6,14 @@ Contributors and contributions are welcome. Please read these guidelines first.
 
 The project homepage is on [GitHub](https://github.com/sr-murthy/fsrapiclient).
 
-Contributors can open pull requests from a fork targeting the parent `main`[branch](https://github.com/sr-murthy/fsrapiclient/tree/main). Butit may be a good first step to create an[issue](https://github.com/sr-murthy/fsrapiclient/issues) or open a [discussion topic](https://github.com/sr-murthy/fsrapiclient/discussions).
+Contributors can open pull requests from a fork targeting the parent [main branch](https://github.com/sr-murthy/fsrapiclient/tree/main). But it may be a good first step to create an [issue](https://github.com/sr-murthy/fsrapiclient/issues) or open a
+[discussion topic](https://github.com/sr-murthy/fsrapiclient/discussions).
 
-A simple Git workflow, using a feature and/or fix branch created off the`main` branch of your fork, is recommended.
+A simple Git workflow, using a feature and/or fix branch created off the `main` branch of your fork, is recommended.
 
 ## Repo
 
-If you wish to contribute please first ensure you have [SSH access toGitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh). This basically involves creating a project-specific SSH keypair - if you don't already have one - and adding it to GitHub. If you have done this successfully then this verification step should work:
+If you wish to contribute please first ensure you have [SSH access to GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh). This basically involves creating a project-specific SSH keypair - if you don’t already have one - and adding it to GitHub. If you have done this successfully then this verification step should work:
 
 ``` shell
 ssh -vT [email protected]
@@ -41,13 +42,12 @@ git clone git+ssh://[email protected]/<fork user>/fsrapiclient
 
 You can create additional remotes for the parent project to enable easier syncing, or you can simply create PRs directly against the parent project.
 
-## Dependencies & PDM
+## Dependencies & PDM `cubes`
 
-The package has only [`requests`](https://requests.readthedocs.io/en/latest/) as a (production) dependency - this and its sub-dependencies are automatically installed on installing the package.
+The package only depends on the [requests](https://requests.readthedocs.io/en/latest/) library.
 
 Development dependencies are specified in the `[tool.pdm.dev-dependencies]` section of the [project
-TOML](https://github.com/sr-murthy/fsrapiclient/blob/main/pyproject.toml), but they are not mandatory. Of these, the most important are probably the `'test'` dependencies, including [pytest](https://docs.pytest.org/en/8.0.x/) and
-[pytest-cov](https://pytest-cov.readthedocs.io/):
+TOML](https://github.com/sr-murthy/fsrapiclient/blob/main/pyproject.toml), but they are not mandatory. Of these, the most important are probably the `'test'` dependencies, including [pytest](https://docs.pytest.org/en/8.0.x/) and [pytest-cov](https://pytest-cov.readthedocs.io/):
 
 ``` toml
 test = [
@@ -60,9 +60,8 @@ test = [
 
 [PDM](https://pdm-project.org/latest) is used (by myself, currently, the sole maintainer) to manage all dependencies and publish packages to PyPI. It is also used to automate certain tasks, such as running tests, as described in the section.
 
-There are no root-level `requirements*.txt` files - but only a single (default, version-controlled, cross-platform) [pdm.lock](https://github.com/sr-murthy/fsrapiclient/blob/main/pdm.lock) lockfile, which defines metadata for all TOML-defined development
-dependencies, including the currently empty set of production dependencies, and their sub-dependencies etc. This can be used to
-install all development dependencies, including the project itself, in editable mode where available:
+There are no root-level `requirements*.txt` files - but only a single (default, version-controlled, cross-platform)
+[pdm.lock](https://github.com/sr-murthy/fsrapiclient/blob/main/pdm.lock) lockfile, which defines metadata for all TOML-defined development dependencies, including the currently empty set of production dependencies, and their sub-dependencies etc. This can be used to install all development dependencies, including the project itself, in editable mode where available:
 
 ``` shell
 pdm install -v --dev
@@ -71,7 +70,7 @@ pdm install -v --dev
 > [!NOTE]
 > It is important to note that `pdm install` uses either the default lockfile (`pdm.lock`), or one specified with `-L <lockfile>`. Multiple lockfiles can be generated and maintained. Refer to the [PDM install documentation](https://pdm-project.org/latest/reference/cli/#install) for more information.
 
-If you don't wish to install any editable dependencies, including the project itself, you can use:
+If you don’t wish to install any editable dependencies, including the project itself, you can use:
 
 ``` shell
 pdm install -v --dev --no-editable --no-self
@@ -97,8 +96,8 @@ For more information on PDM lockfiles and installing requirements see the [PDM d
 
 Tests are defined in the `tests` folder, and should be run with [pytest](https://pytest-cov.readthedocs.io/en/latest/).
 
-For convenience different types of test targets are defined in the [Makefile](https://github.com/sr-murthy/fsrapiclient/blob/main/Makefile): `lint` for Ruff linting, `doctests` for running [doctests](https://docs.python.org/3/library/doctest.html) and `unittests` for running unittests and measuring coverage, using `pytest`
-and the `pytest-cov` plugin:
+For convenience different types of test targets are defined in the[Makefile](https://github.com/sr-murthy/fsrapiclient/blob/main/Makefile): lint` for Ruff linting, `doctests` for running [doctests](https://docs.python.org/3/library/doctest.html) and
+`unittests` for running unittests and measuring coverage, using `pytest` and the `pytest-cov` plugin:
 
 ``` shell
 make lint
@@ -115,25 +114,22 @@ Unit tests can be run all at once using `make unittests` or individually using `
 python -m pytest -sv tests/units/test_api.py::TestFsrApiClient
 ```
 
-> [!NOTE]
-> The `-s` option in the `pytest` command is to allow interactive environments to be entered on errors, e.g. debugger breakpoints. The default behaviour of [capturing console input/output](https://docs.pytest.org/en/stable/how-to/capture-stdout-stderr.html#default-stdout-stderr-stdin-capturing-behaviour) would otherwise prevent debuggers from being triggered.
-
 The doctests serve as acceptance tests, and are best run after the unit tests. They can be run all at once using `make doctests`, or individually by library using `python -m doctest`, e.g. running all the doctests in `fsrapiclient.api`:
 
 ``` shell
 python -m doctest -v src/fsrapiclient/api.py
 ```
 
-## Documentation
+## Documentation `book`
 
 Detailed documentation can be found [here](https://fsrapiclient.readthedocs.io).
 
-## CI
+## CI `circle-play`
 
 The CI pipelines are defined in the [CI YML](https://github.com/sr-murthy/fsrapiclient/blob/main/.github/workflows/ci.yml)
 and the [CodeQL Analysis YML](https://github.com/sr-murthy/fsrapiclient/blob/main/.github/workflows/codeql-analysis.yml). Currently, pipelines for all branches include a tests stage that includes Ruff linting, unit tests, Python doctests, and in that order.
 
-## Versioning and Releases
+## Versioning and Releases `upload`
 
 The [PyPI package](https://pypi.org/project/fsrapiclient/) is currently at version `0.2.1`.
 

README.md

@@ -22,12 +22,11 @@ A lightweight Python client library for the UK [Financial Services Register (FS
 The FS Register is a **public** database of all firms, individuals, funds, and other entities, that are either currently, or have been previously, authorised and/or regulated by the UK [Financial Conduct Authority (FCA)](https://www.fca.org.uk) and/or the [Prudential Regulation Authority (PRA)](http://bankofengland.co.uk/pra).
 
 > [!NOTE]
-> The FS Register API is free to use but accessing it, including via this library, requires [registration](https://register.fca.org.uk/Developer/ShAPI_LoginPage?ec=302&startURL=%2FDeveloper%2Fs%2F#). Registration involves a free sign up with an email, which is used as the API username in requests, and basic personal information. Once registered an API key is available from your registration profile - the API key can be used in request headers to programmatically make requests via any suitable language and library of choice.
+> The FS Register API is free to use but accessing it, including via this library, requires [registration](https://register.fca.org.uk/Developer/ShAPI_LoginPage?ec=302&startURL=%2FDeveloper%2Fs%2F#). Registration involves a free sign up with an email, which is used as the API username in requests, and basic personal information. Once registered an API key is available from your registration profile.
 
 See the [Sphinx documentation](https://fsrapiclient.readthedocs.io) for more details on:
 
 * [understanding the FS Register API](https://fsrapiclient.readthedocs.io/sources/fs-register-api.html)
-* [package installation](https://fsrapiclient.readthedocs.io/sources/getting-started.html)
 * [usage](https://fsrapiclient.readthedocs.io/sources/usage.html)
 * [contributing](https://fsrapiclient.readthedocs.io/sources/contributing.html)
 * [API reference](https://fsrapiclient.readthedocs.io/sources/api-reference.html)

docs/index.rst

@@ -4,12 +4,12 @@ fsrapiclient
 
 A lightweight Python client library and package for the UK `Financial Services Register (FS Register) <https://register.fca.org.uk/s/>`_ `RESTful API <https://register.fca.org.uk/Developer/s/>`_.
 
-The FS Register is a **public** database of all firms, individuals, funds, and other entities, that are either currently, or have been previously, authorised and/or regulated by the UK `Financial Conduct Authority (FCA) <https://www.fca.org.uk>`__ and/or the `Prudential Regulation Authority (PRA) <http://bankofengland.co.uk/pra>`__.
+The FS Register is a **public** database of all firms, individuals, funds, and other entities, that are either currently, or have been previously, authorised and/or regulated by the UK `Financial Conduct Authority (FCA) <https://www.fca.org.uk>`_ and/or the `Prudential Regulation Authority (PRA) <http://bankofengland.co.uk/pra>`_.
 
 .. note::
 
    The FS Register API is free to use but accessing it, including via this library, requires
-   `registration <https://register.fca.org.uk/Developer/ShAPI_LoginPage?ec=302&startURL=%2FDeveloper%2Fs%2F#>`_. Registration involves a free sign up with an email, which is used as the API username in requests, and basic personal information. Once registered an API key is available from your registration profile - the API key can be used in request headers to programmatically make requests via any suitable language and library of choice.
+   `registration <https://register.fca.org.uk/Developer/ShAPI_LoginPage?ec=302&startURL=%2FDeveloper%2Fs%2F#>`_. Registration involves a free sign up with an email, which is used as the API username in requests, and basic personal information. Once registered an API key is available from your registration profile.
 
 To learn more about the FS Register API structure please consult the `official documentation <https://register.fca.org.uk/Developer/s/>`_, or start :doc:`here <sources/fs-register-api>`.
 

docs/sources/contributing.rst

@@ -128,14 +128,6 @@ Unit tests can be run all at once using :command:`make unittests` or individuall
 
    python -m pytest -sv tests/units/test_api.py::TestFsrApiClient
 
-..
-
-   [!NOTE] The ``-s`` option in the ``pytest`` command is to allow
-   interactive environments to be entered on errors, e.g. debugger
-   breakpoints. The default behaviour of `capturing console
-   input/output <https://docs.pytest.org/en/stable/how-to/capture-stdout-stderr.html#default-stdout-stderr-stdin-capturing-behaviour>`_
-   would otherwise prevent debuggers from being triggered.
-
 The doctests serve as acceptance tests, and are best run after the unit tests. They can be run all at once using ``make doctests``, or individually by library using :command:`python -m doctest`, e.g. running all the doctests in :py:mod:`fsrapiclient.api`:
 
 .. code:: shell
@@ -149,14 +141,18 @@ Documentation :fas:`book`
 
 Detailed documentation can be found `here <https://fsrapiclient.readthedocs.io>`_.
 
-CI
---
+.. _contributing.ci:
+
+CI :fas:`circle-play`
+=====================
 
 The CI pipelines are defined in the `CI YML <https://github.com/sr-murthy/fsrapiclient/blob/main/.github/workflows/ci.yml>`_
 and the `CodeQL Analysis YML <https://github.com/sr-murthy/fsrapiclient/blob/main/.github/workflows/codeql-analysis.yml>`_. Currently, pipelines for all branches include a tests stage that includes Ruff linting, unit tests, Python doctests, and in that order.
 
-Versioning and Releases
------------------------
+.. _contributing.versioning-and-releases:
+
+Versioning and Releases :fas:`upload`
+=====================================
 
 The `PyPI package <https://pypi.org/project/fsrapiclient/>`_ is currently at version ``0.2.1``.
 

docs/sources/fs-register-api.rst

@@ -12,21 +12,21 @@ The base URL for all API requests is:
 
 .. _fs-register-api.resources-and-request-types:
 
-Resources and Request Types
-===========================
+Resources and Endpoints
+=======================
 
 There are three main categories of resource about which information can be requested from the register via API endpoints:
 
-- **firms** - authorised and/or regulated firms (either current or past), or providing regulated products or services
-- **individuals** - individuals associated with the type of firms described above, either current or past
-- **funds** - investment funds or collective investment schemes (CIS),including subfunds of funds
+- **firms** - authorised and/or regulated firms (either current or past), or providing regulated products or services. These are described in more detail :ref:`here <fs-register-api.firm-requests>`.
+- **individuals** - individuals associated with the type of firms described above, either current or past.  These are described in more detail :ref:`here <fs-register-api.individual-requests>`.
+- **funds** - investment funds or collective investment schemes (CIS),including subfunds of funds. These are described in more detail :ref:`here <fs-register-api.fund-requests>`.
 
-There is also a **common search** API endpoint that allows a search for any of these resources by a name substring and a corresponding type specification (firm, individual, or fund).
+There is also a **common search** API endpoint that allows a search for any of these resources by a name substring and a corresponding type specification (firm, individual, or fund). This is described in more detail :ref:`here <fs-register-api.common-search-requests>`.
 
 .. _fs-register-api.request-headers:
 
 Request Headers
----------------
+===============
 
 The FS Register API is read-only - all requests must use ``GET``, and include headers containing the API username and key:
 
@@ -39,7 +39,7 @@ The FS Register API is read-only - all requests must use ``GET``, and include he
 .. _fs-register-api.rate-limiting:
 
 Rate Limiting
--------------
+=============
 
 According to the `API documentation <https://register.fca.org.uk/Developer/s/>`__ **rate limiting** is applied to set a **maximum of 50 requests per 10 seconds per user**, and **breaches** lead to `(HTTP 429) errors <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429>`__ and **requests being blocked for 1 minute**.
 
@@ -50,9 +50,9 @@ According to the `API documentation <https://register.fca.org.uk/Developer/s/>`_
 .. _fs-register-api.firm-requests:
 
 Firm Requests
--------------
+=============
 
-Firms are identified by unique firm reference numbers (FRN). The following is a table summarising firm-specific API endpoints:
+Firms are identified by unique firm reference numbers (FRN). The following table summarises firm-specific API endpoints.
 
 +-----------------------------------+------------------------+---------+
 | API endpoint                      | Parameters             | Request |
@@ -99,9 +99,9 @@ Firms are identified by unique firm reference numbers (FRN). The following is a
 .. _fs-register-api.individual-requests:
 
 Individual Requests
--------------------
+===================
 
-Individuals associated with firms are identified by unique individual reference numbers (IRN). and the following is a table summarising individual-specific API endpoints.
+Individuals associated with firms in the FS Register are identified by unique individual reference numbers (IRN). The following table summarises individual-specific API endpoints.
 
 +-------------------------------------------------+------------+----------------+
 | API endpoint                                    | Parameters | Request Method |
@@ -120,9 +120,9 @@ Individuals associated with firms are identified by unique individual reference
 .. _fs-register-api.fund-requests:
 
 Fund Requests
--------------
+=============
 
-Funds are identified by unique product reference numbers (PRN). The following is a table summarising fund-specific API endpoints:
+Funds, also referred to as collective investment schemes (CIS) in the FS Register, are identified by unique product reference numbers (PRN). The following table summarises fund-specific API endpoints.
 
 =========================== ========== ==============
 API endpoint                Parameters Request Method
@@ -135,7 +135,7 @@ API endpoint                Parameters Request Method
 .. _fs-register-api.common-search-requests:
 
 Common Search Requests
-----------------------
+======================
 
 The common search API endpoint has the following request structure: