profiles: Use admonitions and copy-edit

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:
 

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

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.

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.