Revise and expand implementation docs

README.rst

@@ -20,18 +20,15 @@ sdmx: Statistical data and metadata exchange
 `Source code @ Github <https://github.com/khaeru/sdmx/>`_ —
 `Authors <https://github.com/khaeru/sdmx/graphs/contributors>`_
 
-`sdmx` is a Python package that implements `SDMX <http://www.sdmx.org>`_ 2.1 (`ISO 17369:2013 <https://www.iso.org/standard/52500.html>`_) and 3.0, which are standards and formats for exchange of **statistical data and metadata** that are developed and used by national statistical agencies, central banks, and international organisations.
+``sdmx`` (`‘sdmx1’ on PyPI <https://pypi.org/project/sdmx1>`_) is a Python implementation of the `SDMX <http://www.sdmx.org>`_ 2.1 (`ISO 17369:2013 <https://www.iso.org/standard/52500.html>`_) and 3.0 standards for **statistical data and metadata exchange**.
+The SDMX standards are developed and used by national statistical agencies, central banks, and international organisations.
 
-`sdmx` can be used to:
+``sdmx`` can be used to:
 
-- explore the data available from `data providers <https://sdmx1.rtfd.io/en/latest/sources.html>`_ such as the World Bank, International Monetary Fund, Eurostat, OECD, and United Nations;
-- read and write data and metadata in SDMX formats including SDMX-ML (XML) and SDMX-JSON, either:
-
-  - from local files, or
-  - retrieved from SDMX web services, with query validation and caching;
-
-- convert data and metadata into `pandas <https://pandas.pydata.org>`_ objects, for use with the analysis, plotting, and other tools in the Python data science ecosystem;
-- apply the `SDMX Information Model <https://sdmx1.rtfd.io/en/latest/api.rst#api-model>`_ to your own data;
+- Explore and retrieve data available from SDMX-REST `web services <https://sdmx1.rtfd.io/en/latest/sources.html>`_ operated by providers including the World Bank, International Monetary Fund, Eurostat, OECD, and United Nations;
+- Read and write data and metadata in file formats including SDMX-ML (XML), SDMX-JSON, and SDMX-CSV;
+- Convert data and metadata into `pandas <https://pandas.pydata.org>`_ objects, for use with the analysis, plotting, and other tools in the Python data science ecosystem;
+- Apply the `SDMX information model <https://sdmx1.rtfd.io/en/latest/api.rst#api-model>`_ to structure and publish your own data;
 
 …and much more.
 

doc/api/model.rst

@@ -7,6 +7,8 @@
 SDMX Information Model
 **********************
 
+See the :ref:`implementation notes <im>`.
+
 Quick links to classes common to SDMX 2.1 and 3.0 (in alphabetical order):
 
 .. include:: model-common-list.rst

doc/api/reader.rst

@@ -1,5 +1,5 @@
-Parse SDMX file formats
-***********************
+Read SDMX file formats
+**********************
 
 SDMX-ML
 =======
@@ -32,8 +32,6 @@ Implementation details:
 .. automodule:: sdmx.reader.xml.v30
    :members:
 
-
-
 SDMX-JSON
 =========
 

doc/api/writer.rst

@@ -1,7 +1,12 @@
 .. currentmodule:: sdmx.writer
 
-Convert ``sdmx`` objects to other formats
-*****************************************
+Writer/convert :mod:`sdmx` objects
+**********************************
+
+The term **write** refers to both:
+
+- Converting :mod:`sdmx.message` and :mod:`sdmx.model` objects to the SDMX standard file formats.
+- Converting :mod:`sdmx.model` objects to :mod:`pandas` objects.
 
 .. _writer-csv:
 

doc/conf.py

@@ -80,7 +80,7 @@ def linkcode_resolve(domain, info):
 
 # -- Options for sphinx.ext.napoleon ---------------------------------------------------
 
-napolean_preprocess_types = True
+napoleon_preprocess_types = True
 
 # -- Options for sphinx.ext.todo -------------------------------------------------------
 

doc/dev.rst

@@ -7,13 +7,17 @@ Contributions are welcome!
 - For current development priorities, see the list of `GitHub milestones <https://github.com/khaeru/sdmx/milestones>`_ and issues/PRs targeted to each.
 - For wishlist features, see issues on GitHub tagged `‘enh’ <https://github.com/khaeru/sdmx/labels/enh>`_ or `‘wishlist’ <https://github.com/khaeru/sdmx/labels/wishlist>`_.
 
+.. _code-style:
+
 Code style
 ==========
 
 - This project uses, via `pre-commit <https://pre-commit.com>`_:
 
-  - `black <https://black.readthedocs.io>`_ code style,
-  - `ruff <https://beta.ruff.rs/docs/>`_ to ensure `PEP 8 <https://www.python.org/dev/peps/pep-0008>`_ compliance and consistent order for imports (superseding `flake8 <https://flake8.pycqa.org>`_ and `isort <https://pypi.org/project/isort/>`_), and
+  - `ruff <https://beta.ruff.rs/docs/>`_ for code style and linting, including:
+
+     - ensure `PEP 8 <https://www.python.org/dev/peps/pep-0008>`_ compliance, and
+     - ensure a consistent order for imports (superseding `flake8 <https://flake8.pycqa.org>`_ and `isort <https://pypi.org/project/isort/>`_).
   - `mypy <https://mypy.readthedocs.io>`_ for static type checking.
 
   These **must** be applied to new or modified code.
@@ -158,6 +162,7 @@ Internal code reference
    :undoc-members:
    :show-inheritance:
 
+
 Inline TODOs
 ============