Add RFCs into the website

Author: birkenfeld

.github/workflows/publish-pages.yml

@@ -1,14 +1,10 @@
-# This is a basic workflow to help you get started with Actions
-
 name: deploy_sphinx
 
 permissions:
   id-token: write
   pages: write
 
-# Controls when the workflow will run
 on:
-  # Triggers the workflow on push or pull request events but only for the "master" branch
   push:
     branches: [ "master" ]
   # dispatch from the main repo, needs PAT with access to both repos
@@ -21,17 +17,16 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
       - uses: actions/checkout@v4
       - name: Checkout spec repo
         uses: actions/checkout@v4
         with:
           repository: SampleEnvironment/SECoP
           path: ./SECoP
-      - name: copy spec into correct folder
+      - name: copy over spec
         run: cp -r ./SECoP/protocol/specification/* source/specification
-      - name: copy 1-0 spec into correct folder
-        run: cp ./SECoP/protocol/SECoP_Specification_V1.0.rst source/specification/SECoP_Specification_V1.0.rst
+      - name: process rfcs
+        run: python process_rfcs.py ./SECoP/rfcs source/rfcs
       - name: Import secop-img SVGs
         uses: robinraju/[email protected]
         with:

.gitignore

@@ -1,3 +1,4 @@
 build/
 .venv/
 __pycache__/
+source/rfcs/[0-9]*

process_rfcs.py

@@ -0,0 +1,67 @@
+import pathlib
+import sys
+
+sourcedir = pathlib.Path(sys.argv[1])
+destdir = pathlib.Path(sys.argv[2])
+
+rfcs = []
+
+for rfc in sourcedir.glob('RFC-*.rst'):
+    if rfc.name.startswith('RFC-000'):
+        continue
+
+    n = rfc.name.split('-')[1]
+
+    with open(rfc, 'r', encoding='utf-8') as f:
+        lines = f.readlines()
+
+    assert lines[0].startswith('- Feature: ')
+    raw_title = lines[0][10:].strip()
+    title = f'RFC {n}: {raw_title}'
+    assert lines[1].startswith('- Status: ')
+    status = lines[1][10:].strip()
+    lines[:1] = [
+        '.. _rfc-' + n + ':\n',
+        '\n',
+        title + '\n',
+        '@' * len(title) + '\n',
+        '\n',
+    ]
+
+    new_name = rfc.name.removeprefix('RFC-')
+
+    dest_file = destdir / new_name
+    with open(dest_file, 'w', encoding='utf-8') as f:
+        f.writelines(lines)
+
+    rfcs.append((new_name.removesuffix('.rst'), n, raw_title, status))
+
+rfcs.sort()
+
+with open(destdir / 'index.rst', 'r', encoding='utf-8') as f:
+    lines = f.readlines()
+
+with open(destdir / 'index.rst', 'w', encoding='utf-8') as f:
+    for line in lines:
+        if line.strip() == '.. toctree::':
+            f.write(line)
+            f.write('   :maxdepth: 1\n')
+            f.write('   :hidden:\n\n')
+            for ref in rfcs:
+                f.write(f'   {ref[0]}\n')
+
+            f.write('\n')
+            f.write('.. list-table::\n')
+            f.write('   :widths: 10 70 20\n')
+            f.write('   :header-rows: 1\n\n')
+            f.write('   * - #\n')
+            f.write('     - Title\n')
+            f.write('     - Status\n')
+            for ref, n, title, status in rfcs:
+                f.write(f'   * - {n}\n')
+                f.write(f'     - :ref:`{title} <rfc-{n}>`\n')
+                f.write(f'     - {status}\n')
+
+            break
+
+        f.write(line)

secop_sphinx.py

@@ -1,13 +1,7 @@
 import re
 
-from docutils import nodes
-
 from sphinx import addnodes
 from sphinx.domains.python import PyFunction, PyVariable, PyObject, PyClasslike
-from sphinx.util.docutils import ReferenceRole
-from sphinx.util.nodes import split_explicit_title
-
-REPO_BASE = 'https://github.com/SampleEnvironment/SECoP/blob/master/'
 
 
 class Property(PyVariable):
@@ -105,27 +99,6 @@ def get_index_text(self, modname, name_cls):
         return '%s (protocol message)' % name_cls[0]
 
 
-class SecopRFC(ReferenceRole):
-    def run(self):
-        target_id = 'index-%s' % self.env.new_serialno('index')
-        entries = [('single', 'SECoP RFC; RFC %s' % self.target,
-                    target_id, '', None)]
-
-        index = addnodes.index(entries=entries)
-        target = nodes.target('', '', ids=[target_id])
-        self.inliner.document.note_explicit_target(target)
-
-        refuri = REPO_BASE + f'rfcs/RFC-{self.target}.rst'
-        reference = nodes.reference('', '', internal=False, refuri=refuri)
-        if self.has_explicit_title:
-            reference += nodes.strong(self.title, self.title)
-        else:
-            num = self.target.split('-')[0]
-            title = f'SECoP RFC {num}'
-            reference += nodes.strong(title, title)
-        return [index, target, reference], []
-
-
 def setup(app):
     app.add_directive('node-property', Property)
     app.add_directive('mod-property', Property)
@@ -137,5 +110,4 @@ def setup(app):
     app.add_directive('feature', Feature)
     app.add_directive('message', Message)
     app.add_directive('errorclass', ErrorClass)
-    app.add_role('secop-rfc', SecopRFC())
     return {'parallel_read_safe': True, 'version': '0.1.0'}

source/index.rst

@@ -13,6 +13,7 @@ Welcome to SECoP!
     specification/index
     howtos/index
     implementations/index
+    rfcs/index
     contact
     ISSE <https://sampleenvironment.org/>
     privacy-policy

source/rfcs/index.rst

@@ -0,0 +1,10 @@
+SECoP RFCs
+==========
+
+RFCs are the primary mechanism for further development of SECoP.  Everyone in
+the community is welcome to create a new RFC for the committee to discuss, see
+:ref:`rfc-001` for details.
+
+.. toctree::
+
+.. Everything else in here is automatically generated by ``process_rfcs.py``.