software-origins/nixguix: Document the origins

Refs. swh/devel/swh-loader-core#4749

docs/user/software-origins/nixguix.rst

@@ -8,12 +8,56 @@ Nix and Guix
 
 .. include:: dynamic/nixguix_status.inc
 
+This page documents how |swh| archives source packages from the
+`GNU Guix <https://guix.gnu.org/>`_ and `Nix <https://nixos.org/>`_
+distributions.
+
+Those distributions provide functional package managers, respectively GNU Guix and Nix
+with similar properties (e.g. transactional, declarative up to the operating system,
+reproducible, ...). Definition of packages is dependent on their respective DSL. As it
+was not parsable easily nor listing api existed, community effort was done upstream to
+provide regular extraction of an origin listing (as json manifest).
+
+|swh|'s NixGuix lister queries respectively those remote origins listing. They contain
+various types of origins.
+
+As a result |swh| has a lister and various loaders to deal with those origins. Those
+origins can be:
+- simple file, with visit type 'content'
+- tarballs with visit type 'tarball-directory'
+- :ref:`Svn <user-software-origins-svn>` repository (full with visit type 'svn', or at a specific revision, visit type 'svn-export')
+- :ref:`Git <user-software-origins-git>` repository (full with visit type 'git' or at a specific commit, visit type 'git-checkout')
+- :ref:`Mercurial <user-software-origins-mercurial>` repository (full with visit type 'hg' or at a specific hg changeset, visit type 'hg-checkout').
+
+Origin URLs match each main url provided in the manifest.
+
+For some cases, there can be mirror urls which are used as fallback artifact retrieval
+when the main url is no longer available.
+
+No extrinsic nor intrinsic metadata is happening on the lister's side.
+
+But for some kind of origins, 'content', 'tarball-directory', 'svn-export',
+'hg-checkout', 'git-checkout', extra information regarding the checksums used
+('standard', e.g. sha256, or 'nar', specific intrinsic identifier used by Guix and Nix),
+are transmitted to their respective loaders. During their respective ingestion, those
+checksums are verified. If the checksum does not match, the artifact is rejected and the
+visit is failed. If not, the artifact is ingested. Note that a new entry is recorded in
+the ExtID table to map the SWHID of the content or directory ingested to their their
+original checksum.
+
 TODO:
 
-* description of the software origin
 * summary of the lister's algorithm
 * summary of the loader's algorithm
-* URL pattern
-* collect extrinsic metadata?
 * index extrinsic metadata?
 * index intrinsic metadata?
+
+Resources:
+
+* `Gnu Guix git repository <https://git.savannah.gnu.org/cgit/guix.git>`__
+
+* `Nixpkgs git repository <https://github.com/nixos/nixpkgs>`__
+
+* `Remote nixpkgs json manifest <https://nix-community.github.io/nixpkgs-swh/sources-unstable-full.json>`__
+
+- `Remote guix json manifest <https://nix-community.github.io/nixpkgs-swh/>`__