Introduce PGnnnn identifiers for policies

Introduce stable numeric identifiers for policies, and create permalinks
from them.

Signed-off-by: Michał Górny <mgorny@gentoo.org>

13 files changed, 93 insertions, 5 deletions

diff --git a/.gitignore b/.gitignore
index 301101c..ea5fde5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
 /_build/
 /.tox/
+/exts/__pycache__/
diff --git a/conf.py b/conf.py
index e91b613..d622b02 100644
--- a/conf.py
+++ b/conf.py
@@ -11,10 +11,10 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('exts'))
 
 
 # -- Project information -----------------------------------------------------
@@ -38,7 +38,10 @@ release = ''
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.todo']
+extensions = [
+    'policyident',
+    'sphinx.ext.todo',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
diff --git a/dependencies.rst b/dependencies.rst
index 55bba5c..a1f5177 100644
--- a/dependencies.rst
+++ b/dependencies.rst
@@ -6,6 +6,7 @@ Dependencies
 
 Optional runtime dependencies
 -----------------------------
+:PG: 0001
 :Source: QA
 :Reference: https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=104017#USE-Controlled_Optional_RDEPENDS
 :Reported: no
@@ -35,6 +36,7 @@ This is especially important for packages that take long time to build.
 
 =-dependencies with no revision
 -------------------------------
+:PG: 0002
 :Source: QA
 :Reported: by repoman and pkgcheck
 
@@ -67,6 +69,7 @@ Slot and subslot dependencies
 
 on (sub-)slotted packages
 ~~~~~~~~~~~~~~~~~~~~~~~~~
+:PG: 0011
 :Source: QA
 :Reference: https://archives.gentoo.org/gentoo-portage-dev/message/9cae3a92412a007febe7ac0612d50f5f
 :Reported: by repoman and pkgcheck
@@ -100,6 +103,7 @@ means 'verified that any slot is acceptable'.
 
 special case: Qt packages
 ~~~~~~~~~~~~~~~~~~~~~~~~~
+:PG: 0012
 :Source: Qt project
 :Reference: https://wiki.gentoo.org/wiki/Project:Qt/Policies#Dependencies
 :Reported: no
@@ -132,6 +136,7 @@ They point out the case of Qt packages as an example.
 
 Revision bumps on runtime dependency changes
 --------------------------------------------
+:PG: 0003
 :Source: Council
 :Reference: https://projects.gentoo.org/council/meeting-logs/20151011-summary.txt
 :Reported: no
@@ -175,6 +180,7 @@ USE dependencies
 
 on packages without the flag
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+:PG: 0021
 :Source: QA (inferred from PMS)
 :Reported: by pkgcheck
 
diff --git a/ebuild-format.rst b/ebuild-format.rst
index ed9bde0..a5bf5aa 100644
--- a/ebuild-format.rst
+++ b/ebuild-format.rst
@@ -8,6 +8,7 @@ Ebuild file format
 
 Coding style
 ------------
+:PG: 0101
 :Source: QA
 :Reported: partially via repoman and pkgcheck
 
@@ -32,6 +33,7 @@ the ebuild.
 
 Code must be contained within ebuild and eclasses
 -------------------------------------------------
+:PG: 0102
 :Source: QA
 :Reference: https://bugs.gentoo.org/612630
 :Reported: no
@@ -54,6 +56,7 @@ that possibility, including linting tools.
 
 HOMEPAGE must not contain variables
 -----------------------------------
+:PG: 0103
 :Source: QA
 :Reported: by pkgcheck, highlighted as error by gentoo-syntax
 
@@ -73,6 +76,7 @@ as reducing the usefulness of plain tools such as grep.
 
 SRC_URI must not refer to HOMEPAGE
 ----------------------------------
+:PG: 0104
 :Source: QA
 :Reported: by pkgcheck
 
@@ -92,6 +96,7 @@ index.
 
 KEYWORDS must be defined on a single line
 -----------------------------------------
+:PG: 0105
 :Source: QA
 :Reported: no
 
diff --git a/exts/policyident.py b/exts/policyident.py
new file mode 100644
index 0000000..6093c8c
--- /dev/null
+++ b/exts/policyident.py
@@ -0,0 +1,48 @@
+# Handle :PG: policy identifiers for Policy Guide
+# (c) 2020 Michał Górny
+# 2-clause BSD license
+
+from docutils import nodes
+
+from sphinx.util import logging
+
+
+logger = logging.getLogger(__name__)
+
+
+def find_pg_id(section):
+    # first child should be title
+    title = section.children[0]
+    assert isinstance(title, nodes.title)
+    # second child should be field list
+    cl = section.children[1]
+    if not isinstance(cl, nodes.field_list):
+        return None
+
+    for f in cl.traverse(nodes.field):
+        fn = next(iter(f.traverse(nodes.field_name)))
+        fv = next(iter(f.traverse(nodes.field_body)))
+        if fn.astext().upper() == 'PG':
+            if fn.astext() != 'PG':
+                raise RuntimeError('PG field must be uppercase')
+            iv = '{:04d}'.format(int(fv.astext(), 10))
+            if fv.astext() != iv:
+                raise RuntimeError('PG value must be 4 digits, zero-padded ({})'
+                                   .format(iv))
+            return iv
+
+    logger.warning('%s: no PG identifier found', title.astext())
+
+
+def on_doctree_read(app, doctree):
+    for node in doctree.traverse(nodes.section):
+        pg_id = find_pg_id(node)
+        if pg_id is not None:
+            node['ids'].insert(0, 'pg' + pg_id)
+
+
+def setup(app):
+    app.connect('doctree-read', on_doctree_read)
+    return {
+        'version': '0',
+    }
diff --git a/filesystem.rst b/filesystem.rst
index 081ab99..52e20a3 100644
--- a/filesystem.rst
+++ b/filesystem.rst
@@ -5,6 +5,7 @@ File system layout
 
 Installation paths
 ------------------
+:PG: 0201
 :Source: QA
 :Reference: https://gitweb.gentoo.org/repo/gentoo.git/tree/metadata/install-qa-check.d/08gentoo-paths
 :Reported: via install-qa-check.d
@@ -60,6 +61,7 @@ exceptions are:
 
 Support for separate /usr
 -------------------------
+:PG: 0202
 :Source: QA
 :Reference: https://projects.gentoo.org/council/meeting-logs/20130813-summary.txt
             https://projects.gentoo.org/council/meeting-logs/20130924-summary.txt
@@ -79,6 +81,7 @@ from rootfs to initramfs.
 
 Strict multilib layout
 ----------------------
+:PG: 0203
 :Source: QA
 :Reference: https://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80multilib-strict
 :Reported: via install-qa-check.d, fatal
@@ -103,6 +106,7 @@ to be correctly found by the dynamic loader.
 
 Static libraries and libtool files
 ----------------------------------
+:PG: 0204
 :Source: QA
 :Reference: https://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80libraries
 :Reported: via install-qa-check.d, fatal
@@ -124,6 +128,7 @@ be a waste of space.
 
 Game install locations and ownership
 ------------------------------------
+:PG: 0205
 :Source: Council, clarified by QA
 :Reference: https://projects.gentoo.org/council/meeting-logs/20151213-summary.txt
             https://projects.gentoo.org/council/meeting-logs/20151011-summary.txt
@@ -160,6 +165,7 @@ fulfill that purpose.
 
 Absolute symbolic link targets
 ------------------------------
+:PG: 0206
 :Source: QA
 :Reported: by repoman and pkgcheck (when ebuild-generated)
 
diff --git a/installed-files.rst b/installed-files.rst
index b77bc02..c8c55f2 100644
--- a/installed-files.rst
+++ b/installed-files.rst
@@ -7,6 +7,7 @@ Installed files
 
 Installation of small files
 ---------------------------
+:PG: 0301
 :Source: QA
 :Reported: no
 
@@ -40,6 +41,7 @@ such a huge package in order to install one tiny file.
 
 Installation of static libraries
 --------------------------------
+:PG: 0302
 :Source: QA
 :Reported: no
 
@@ -61,6 +63,7 @@ libraries if they are never going to be used.
 
 Installation of libtool (.la) files
 -----------------------------------
+:PG: 0303
 :Source: QA
 :Reported: no
 
diff --git a/keywords.rst b/keywords.rst
index 272dca4..81db271 100644
--- a/keywords.rst
+++ b/keywords.rst
@@ -5,6 +5,7 @@ Keywording and stabilization
 
 Rekeywording on dropped keywords
 --------------------------------
+:PG: 0401
 :Source: QA
 :Reported: by pkgcheck and repoman
 
@@ -23,6 +24,7 @@ a new version or to remove an old version.
 
 Stabilizing new versions
 ------------------------
+:PG: 0402
 :Source: QA
 :Reported: by pkgcheck
 
@@ -50,6 +52,7 @@ requested on remaining architectures in the first place.
 
 Removing stable keywords
 ------------------------
+:PG: 0403
 :Source: QA
 :Reference: https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=126033#Dropping_Stable_KEYWORDs
 :Reported: n/a
diff --git a/languages.rst b/languages.rst
index b84a80c..dc3a142 100644
--- a/languages.rst
+++ b/languages.rst
@@ -13,6 +13,7 @@ Python
 
 Eclass usage
 ~~~~~~~~~~~~
+:PG: 0501
 :Source: Python project
 :Reference: https://wiki.gentoo.org/wiki/Project:Python/Eclasses
 :Reported: by pkgcheck
@@ -41,6 +42,7 @@ implementations with minimal changes to existing ebuilds.
 
 Python 2 deprecation
 ~~~~~~~~~~~~~~~~~~~~
+:PG: 0502
 :Source: Python project
 :Reference: https://wiki.gentoo.org/wiki/Project:Python#Python_2_end-of-life
 :Reported: no
diff --git a/maintainer.rst b/maintainer.rst
index 07dd3b1..e37daf4 100644
--- a/maintainer.rst
+++ b/maintainer.rst
@@ -5,6 +5,7 @@ Package Maintainers
 
 Adding new maintainers
 ----------------------
+:PG: 0601
 :Source: QA
 :Reported: no
 
@@ -31,6 +32,7 @@ them from packages actually within project's profile was hard.
 
 New packages without a maintainer
 ---------------------------------
+:PG: 0602
 :Source: QA
 :Reported: no
 
@@ -50,6 +52,7 @@ to take care of them.
 
 Removing package maintainers
 ----------------------------
+:PG: 0603
 :Source: QA
 :Reported: no
 
diff --git a/other-metadata.rst b/other-metadata.rst
index 14651cf..c59e0c2 100644
--- a/other-metadata.rst
+++ b/other-metadata.rst
@@ -6,6 +6,7 @@ Other metadata variables
 
 Dynamic slots (multislot flag)
 ------------------------------
+:PG: 0701
 :Source: QA (inferred from PMS)
 :Reference: https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=109991#multislot.2FUSE-dependent_SLOT
 :Reported: ``use`` in global scope triggers fatal error
@@ -42,6 +43,7 @@ invalidation or explicit errors.
 
 HOMEPAGE value must be meaningful
 ---------------------------------
+:PG: 0702
 :Source: QA
 :Reference: https://archives.gentoo.org/gentoo-dev/message/83cc5bbd7bbe8bdf04dd3c3bc7f8a035
 :Reported: known bad values are reported by pkgcheck
@@ -69,6 +71,7 @@ easy to identify such packages.
 
 RESTRICT=test for USE=-test
 ---------------------------
+:PG: 0703
 :Source: QA
 :Reported: by pkgcheck
 
@@ -98,6 +101,7 @@ this circumstance, and they will not fail for users.
 
 LICENSE
 -------
+:PG: 0704
 :Source: QA
 :Reported: no
 
diff --git a/use-flags.rst b/use-flags.rst
index c6a8b4a..4344edc 100644
--- a/use-flags.rst
+++ b/use-flags.rst
@@ -8,6 +8,7 @@ USE flags
 
 Versioned USE flags
 -------------------
+:PG: 0801
 :Source: QA
 :Reference: https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=109991#Versioned_USE_flags
 :Reported: no
@@ -38,6 +39,7 @@ with the QA team before introduction.
 
 USE=gui flag
 ------------
+:PG: 0802
 :Source: QA
 :Reference: https://archives.gentoo.org/gentoo-dev/message/cf3f5a59ac918335766632bd02438722
 :Reported: no
@@ -61,6 +63,7 @@ multiple GUIs.
 
 Underscores in USE flag names
 -----------------------------
+:PG: 0803
 :Source: Council
 :Reference: https://projects.gentoo.org/council/meeting-logs/20191013-summary.txt
 :Reported: by pkgcheck
diff --git a/user-group.rst b/user-group.rst
index 389f3b9..09944a5 100644
--- a/user-group.rst
+++ b/user-group.rst
@@ -6,6 +6,7 @@ Users and groups
 
 User and group account policy
 -----------------------------
+:PG: 0901
 :Source: QA
 :Reference: https://bugs.gentoo.org/702460
 :Reported: by repoman and pkgcheck (as deprecated eclass)