Merge pull request #823 from swcurran/mkdocs

First draft of the Aries RFCs website -- generation and publishing

.github/workflows/publish-site.yml

@@ -0,0 +1,39 @@
+name: publish-docs 
+
+on:
+  push:
+    # Publish `main` as latest, and when pushes are done to branches with "v-doc" prefix
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # fetch all commits/branches
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - uses: actions/cache@v4
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - name: Install Python dependencies
+        run: pip install -r ./mkdocs-requirements.txt
+      - name: Configure git user
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+
+      - name: Deploy docs
+        run: |
+          python --version
+          # Generate the content into the docs folder
+          code/genSite.sh
+          mike deploy --push --update-aliases $VERSION $ALIAS
+          mike set-default latest

.gitignore

@@ -5,3 +5,4 @@ __pycache__
 *.pyc
 *.tmp
 .pytest_cache
+docs

code/aipUpdates.py

@@ -17,6 +17,7 @@
 parser.add_argument('--version', '-v', help='The AIP version to display. Defaults to the current version(s) in the local file')
 parser.add_argument('--diffs', '-d', dest='diffs', action='store_true',
                     help='Display the diffs of any updated RFCs found')
+parser.add_argument('--list', '-l', help='List the RFCs and commits in the AIP with a prefixed by the name of a (for example) shell script')
 
 # parse the arguments
 args = parser.parse_args()
@@ -64,10 +65,10 @@ def readAIP( aip_path, version ):
     if aip_version:
         # Check if we want all the AIPs in the file or this one
         if ( not(args.version) or aip_version.group(1) == args.version ):
-            print("Aries Interop Profile: %s" % (aip_version.group(1)))
+            print("# Aries Interop Profile: %s" % (aip_version.group(1)))
             ListVersionRFCs = True
         else:
-            # Not this one...don't list the changed verion
+            # Not this one...don't list the changed version
             ListVersionRFCs = False
 
     rfc = re.search(_aip_commit_and_file, line)
@@ -78,7 +79,9 @@ def readAIP( aip_path, version ):
         protocol = rfc.group(5)
         changed = re.search(protocol, subprocess.run(['git', 'diff', '--name-only', commit, 'main'], stdout=subprocess.PIPE).stdout.decode('utf-8'))
         # Has this RFC changed since it was set in the RFC?
-        if changed:
+        if args.list:
+            print('%s %s %s' % (args.list, protocol, commit))
+        elif changed:
             # Yes - list it.
             print('>>>>>>>> Changed protocol: %s, latest commit to protocol: %s' % (protocol, 
                 subprocess.run(['git', 'log', '-n', '1', '--pretty=format:%H', '--', protocol], stdout=subprocess.PIPE).stdout.decode('utf-8')))

code/cpAIPs.sh

@@ -0,0 +1,19 @@
+#! /bin/bash
+
+# Usage: Given an RFC name and a commit, retrieve all the files of the RFC into the AIP RFC at the right commit.
+# Example: code/cpAIP.sh concepts/0003-protocols c3b0e2120ad24810598375663b6922b980f85d00
+# Designed to fetch files in subdirectories, although it is not clear how to add them to the documentatioon
+
+PROTOCOL=$1
+COMMIT=$2
+AIP2=aip2
+
+# echo Getting AIP docs for RFC $PROTOCOL, Commit $COMMIT
+cd docs
+for i in $(find $PROTOCOL -type f); do
+    AIPFile=$(echo $i | sed -r "s#(features|concepts)/#${AIP2}/#")
+    # echo $i $AIPFile
+    mkdir -p $(dirname $AIPFile)
+    curl -s https://raw.githubusercontent.com/hyperledger/aries-rfcs/${COMMIT}/$i -o $AIPFile
+done
+cd ..

code/genSite.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+
+# echo Updating the Docs for Aries RFCs
+
+# Clean out the docs folder
+rm -rf docs/*
+mkdir -p docs
+
+# Root folder -- README.md
+cp -r contributing.md github-issues.md MAINTAINERS.md README.md SECURITY.md tags.md 0000*.md *.png collateral docs
+cp LICENSE docs/LICENSE.md
+sed -e "s#/tags.md#tags.md#g" index.md > docs/RFCindex.md
+
+# Features and Concept -- collect all of the RFCs
+cp -r features concepts docs
+
+# Make a copy of AIP 2 RFCs using the right commit for each
+python code/aipUpdates.py -v 2.0 -l "./code/cpAIPs.sh" | \
+   sed -e "/0317-please-ack/d" -e "/0587-encryption-envelope-v2/d" -e "/0627-static-peer-dids/d" \
+   > copy_aip.sh
+source copy_aip.sh
+rm copy_aip.sh
+
+# Cleanup the links in the RFCs
+for i in docs/features/*/README.md docs/concepts/*/README.md docs/aip2/*/README.md; do 
+   sed \
+     -e 's#(/#(../../#g' \
+     -e 's#index.md#RFCindex.md#' \
+     $i >$i.tmp
+   mv $i.tmp $i
+done
+
+# Remove the existing AIP and By Status Links -- we'll add them back
+MKDOCS=mkdocs.yml
+MKDOCSTMP=${MKDOCS}.tmp
+MKDOCSIDX=mkdocs_index.yml
+
+# Strip off the old navigation
+sed '/RFCs by AIP and Status/,$d' ${MKDOCS} >${MKDOCSTMP}
+
+# Add back in the marker
+echo '# RFCs by AIP and Status' >>${MKDOCSTMP}
+
+# Navigation for AIP 2.0 files
+echo "- AIP 2.0:" >>${MKDOCSTMP}
+for i in docs/aip2/*/README.md ; do head -n 1 $i | sed -e "s/# /    - /" -e "s/: / /" -e "s#\$#: $i#" -e "s#docs/##"; done >>${MKDOCSTMP}
+
+# Navigation for all RFCs by Status
+python code/generate_mkdocs_index.py
+cat ${MKDOCSIDX} | sed "s# : concepts/0799#0799 Long Term Support: concepts/0799#" >>${MKDOCSTMP}
+rm ${MKDOCSIDX}
+
+mv ${MKDOCSTMP} ${MKDOCS}

code/generate_mkdocs_index.py

@@ -0,0 +1,46 @@
+import argparse
+from operator import itemgetter
+import os
+from pathlib import Path
+import sys
+
+import rfcs
+
+def update(fname, tmp_fname):
+    if not os.path.exists(fname):
+        os.rename(tmp_fname, fname)
+        # print('Generated %s.' % fname)
+        return
+    with open(fname, encoding='utf-8', mode='rt') as f:
+        old = f.read()
+    with open(tmp_fname, encoding='utf-8', mode='rt') as f:
+        new = f.read()
+    if old == new:
+        # print('No change to %s.' % fname)
+        return
+    os.remove(fname)
+    os.rename(tmp_fname, fname)
+    # print('Updated %s.' % fname)
+
+
+def main(fname = None):
+    if not fname:
+        fname = os.path.join(rfcs.root_folder, 'mkdocs_index.yml')
+    # Load all metadata
+    all = [rfc for rfc in rfcs.walk()]
+    all.sort(key=lambda x: x.num)
+    tmp_fname = fname + '.tmp'
+    with open(tmp_fname, 'w', encoding='utf-8') as out:
+        for status in rfcs.status_list:
+            out.write(f"- {status}:\n")
+            with_status = [rfc for rfc in all if rfc.status == status]
+            for rfc in with_status:
+                out.write(f"    - {rfc.num} {rfc.title}: {rfc.relpath}\n")
+    update(fname, tmp_fname)
+
+
+if __name__ == '__main__':
+    ap = argparse.ArgumentParser('Generate index')
+    ap.add_argument('altpath', metavar='PATH', nargs='?', default=None, help='override where index is generated')
+    args = ap.parse_args()
+    main(args.altpath)

mkdocs-requirements.txt

@@ -0,0 +1,3 @@
+
+mkdocs-material==9.5.10
+mike==2.0.0