docs content

docs/conf.py

@@ -3,3 +3,7 @@
 master_doc = "index"
 
 html_theme = "odsc_default_sphinx_theme"
+
+extensions = [
+    "sphinx.ext.autodoc",
+]

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
+

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.
+
+

docs/python-api/additional_fields.rst

@@ -0,0 +1,7 @@
+Additional Fields
+=================
+
+.. autofunction:: libcove2.common.get_additional_fields_info
+
+
+

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
+

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
+
+
+

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