From df6ef84868abab34f17a1c2edb54c0a416e4984e Mon Sep 17 00:00:00 2001
From: James McKinney <26463+jpmckinney@users.noreply.github.com>
Date: Wed, 6 Dec 2023 21:50:39 -0500
Subject: [PATCH] profiles: Use admonitions and copy-edit

---
 docs/profiles/ppp.rst                  | 14 +++++++++-----
 docs/profiles/technical/build.rst      | 15 ++++++++++-----
 docs/profiles/technical/repository.rst |  6 ++++--
 docs/profiles/translation.rst          |  8 ++++++--
 4 files changed, 29 insertions(+), 14 deletions(-)

diff --git a/docs/profiles/ppp.rst b/docs/profiles/ppp.rst
index 4ba4c1c..6b1e872 100644
--- a/docs/profiles/ppp.rst
+++ b/docs/profiles/ppp.rst
@@ -9,11 +9,13 @@ Maintenance
 Change extensions or version of OCDS
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-See :doc:`technical/build` to:
+.. seealso::
 
--  Change version of OCDS
--  Change extensions
--  Build the profile
+   :doc:`technical/build` to:
+
+   -  Change OCDS version
+   -  Change extensions
+   -  Build the profile
 
 In ``codelists.md``:
 
@@ -29,7 +31,9 @@ To find codelists to add or remove, run (in Bash):
 Translation
 -----------
 
-See the generic profile documentation for :doc:`translation`.
+.. seealso::
+
+   The generic profile documentation for :doc:`translation`
 
 For reference:
 
diff --git a/docs/profiles/technical/build.rst b/docs/profiles/technical/build.rst
index 47ac951..ffa13e6 100644
--- a/docs/profiles/technical/build.rst
+++ b/docs/profiles/technical/build.rst
@@ -1,10 +1,12 @@
 Building the documentation
 ==========================
 
-See the standard's page for :doc:`../../../standard/technical/build`.
+.. seealso::
 
-Change version of OCDS
-----------------------
+   The standard's page for :doc:`../../../standard/technical/build`
+
+Change OCDS version
+-------------------
 
 #. Change ``standard_tag`` and ``standard_version`` in ``conf.py`` to the desired version of OCDS
 #. Update the versions of extensions in ``extension_versions.json``, if appropriate
@@ -13,9 +15,12 @@ Change version of OCDS
 Change extensions
 -----------------
 
-To change the extensions in a profile, change ``extension_versions.json``, then :ref:`profiles/technical/build:Build the profile`.
+#. Edit ``extension_versions.json``
+#. :ref:`profiles/technical/build:Build the profile`
+
+.. note::
 
-Extensions must be in the `extension registry <https://github.com/open-contracting/extension_registry>`__ and should be tagged and released. See :ref:`standard/technical/deployment:Create new versions of extensions`.
+   Extension versions must be in the `extension registry <https://github.com/open-contracting/extension_registry>`__. See :ref:`standard/technical/deployment:Create new versions of extensions`.
 
 Build the profile
 -----------------
diff --git a/docs/profiles/technical/repository.rst b/docs/profiles/technical/repository.rst
index f0f5067..679738b 100644
--- a/docs/profiles/technical/repository.rst
+++ b/docs/profiles/technical/repository.rst
@@ -11,6 +11,8 @@ If a profile has :doc:`moved from ReadTheDocs<integrations>`, it will have ``99.
 Structure
 ---------
 
-See the standard's :ref:`standard/technical/repository:Structure`.
+.. seealso::
 
-The `manage.py <https://github.com/open-contracting/standard_profile_template/blob/latest/manage.py>`__ script called by ``make update`` calls the `build_profile method <https://ocdsextensionregistry.readthedocs.io/en/latest/api/api.html>`__ in ``extension_registry.py``, which compiles a profile's extensions into a consolidated extension, storing the results in ``schema/profile``, and extends OCDS with the consolidated extension, storing the results in ``schema/patched``. It also updates the ``codelists`` field in ``extension.json``. All these built files are version controlled.
+   The standard's page for :ref:`standard/technical/repository:Structure`
+
+``make update`` calls the `manage.py <https://github.com/open-contracting/standard_profile_template/blob/latest/manage.py>`__ script, which calls the `build_profile method <https://ocdsextensionregistry.readthedocs.io/en/latest/api/api.html>`__ in ``extension_registry.py``, which compiles a profile's extensions into a consolidated extension, storing the results in ``schema/profile``, and extends OCDS with the consolidated extension, storing the results in ``schema/patched``. It also updates the ``codelists`` field in ``extension.json``. All these built files are version controlled.
diff --git a/docs/profiles/translation.rst b/docs/profiles/translation.rst
index 93c4977..c1477e4 100644
--- a/docs/profiles/translation.rst
+++ b/docs/profiles/translation.rst
@@ -1,7 +1,9 @@
 Translation
 ===========
 
-See the standard's page for :doc:`../../../standard/translation/index`.
+.. seealso::
+
+   The standard's page for :doc:`../../../standard/translation/index`
 
 The instructions below are similar to others in `ocds-extensions-translations <https://github.com/open-contracting/ocds-extensions-translations#populate-initial-translations>`__ (using the fish shell on macOS). They will, at minimum, pre-translate the text from the unextended schema and codelists.
 
@@ -121,7 +123,9 @@ Pre-translate the profile
 Technical implementation of translation
 ---------------------------------------
 
-See the standard's page for :doc:`../../../standard/translation/implementation`.
+.. seealso::
+
+   The standard's page for :doc:`../../../standard/translation/implementation`
 
 -  ``babel_ocds_codelist.cfg`` indicates the codelist CSV files in the consolidated extension and the patched OCDS (``schema/*/codelists/*.csv``) from which to extract strings to translate.
 -  ``babel_ocds_schema.cfg`` indicates the JSON Schema files in the consolidated extension and the patched OCDS (``schema/*/*-schema.json``) from which to extract strings to translate.