From a7d950cc336ec85ec8604aa43fbac8f92f8b467c Mon Sep 17 00:00:00 2001 From: James B Date: Fri, 4 Oct 2024 09:37:08 +0100 Subject: [PATCH] docs content --- docs/conf.py | 4 ++++ docs/index.rst | 27 +++++++++++++++++++++++++++ docs/migration-from-lib-cove.rst | 13 +++++++++++++ docs/python-api/additional_fields.rst | 7 +++++++ docs/python-api/index.rst | 16 ++++++++++++++++ docs/python-api/org-ids.rst | 9 +++++++++ docs/used-by.rst | 14 ++++++++++++++ 7 files changed, 90 insertions(+) create mode 100644 docs/migration-from-lib-cove.rst create mode 100644 docs/python-api/additional_fields.rst create mode 100644 docs/python-api/index.rst create mode 100644 docs/python-api/org-ids.rst create mode 100644 docs/used-by.rst diff --git a/docs/conf.py b/docs/conf.py index 43ec2e2..bdd8cc6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -3,3 +3,7 @@ master_doc = "index" html_theme = "odsc_default_sphinx_theme" + +extensions = [ + "sphinx.ext.autodoc", +] diff --git a/docs/index.rst b/docs/index.rst index ab3c053..bb3ea00 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,3 +1,30 @@ LibCove2 ======== +This library ultimately supports CoVE web applications, among others. + +CoVE exists to help people: + +* Convert data between common formats (e.g. csv to json) +* Validate data against rules +* Explore data, that machines find easy, but humans find harder to read + +However, CoVE Web App is a separate library +so that you can take the functionality of this library and reuse it in your own applications with your own custom UI. + +Hence this libraries and the libraries that directly use it are pure Python libraries with no UI provided (beyond maybe a simple CLI). + +It is a collection of helper Python functions that may be used by other libraries. + +This gives maximum flexibility to other data standard specific libraries while avoiding those libraries reinventing the wheel. +It also means that if one data standard has a special requirement, +that can usually be handled by the data standard specific library with no need to change this core library. + + +.. toctree:: + :maxdepth: 2 + + python-api/index.rst + migration-from-lib-cove.rst + used-by.rst + diff --git a/docs/migration-from-lib-cove.rst b/docs/migration-from-lib-cove.rst new file mode 100644 index 0000000..df89270 --- /dev/null +++ b/docs/migration-from-lib-cove.rst @@ -0,0 +1,13 @@ +Migration from lib-cove +======================= + + +This library is an updated version of the previous library ( https://github.com/OpenDataServices/lib-cove ). + +However, the structure of the library and how it works have massive changes. +For this reason the upgrade path isn't a simple upgrade, but requires rewriting work in the software that uses this. + +This is why this library is a separate git repository and a separate pypi package, +so that development of the previous library can also continue and users are not forced to upgrade before they are ready. + + diff --git a/docs/python-api/additional_fields.rst b/docs/python-api/additional_fields.rst new file mode 100644 index 0000000..a905802 --- /dev/null +++ b/docs/python-api/additional_fields.rst @@ -0,0 +1,7 @@ +Additional Fields +================= + +.. autofunction:: libcove2.common.get_additional_fields_info + + + diff --git a/docs/python-api/index.rst b/docs/python-api/index.rst new file mode 100644 index 0000000..4c6b46c --- /dev/null +++ b/docs/python-api/index.rst @@ -0,0 +1,16 @@ +Python API +========== + +This section documents the Python API that software using this library should consider. + +It does not document Python that is not intended for reuse by others (you can read the source code for that.) + + +.. toctree:: + :maxdepth: 2 + + org-ids.rst + additional_fields.rst + +TODO schema_dict_fields_generator + diff --git a/docs/python-api/org-ids.rst b/docs/python-api/org-ids.rst new file mode 100644 index 0000000..09063c0 --- /dev/null +++ b/docs/python-api/org-ids.rst @@ -0,0 +1,9 @@ +Org-IDs +======= + +These are functions that are useful for working with data from http://org-id.guide/ + +.. autofunction:: libcove2.common.get_orgids_prefixes + + + diff --git a/docs/used-by.rst b/docs/used-by.rst new file mode 100644 index 0000000..080d562 --- /dev/null +++ b/docs/used-by.rst @@ -0,0 +1,14 @@ +Used by +======= + +This library is directly used by: + +* https://github.com/openownership/lib-cove-bods +* https://github.com/Open-Telecoms-Data/lib-cove-ofds +* https://github.com/GFDRR/rdls-lib-cove + +Those libraries are in turn used for these CoVE web apps: + +* https://github.com/openownership/cove-bods +* https://github.com/Open-Telecoms-Data/cove-ofds +* https://github.com/GFDRR/rdls-cove