raccoongang · wowkalucky · Nov 21, 2023 · Apr 17, 2024 · Nov 30, 2023 · Apr 17, 2024
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,26 @@
+name: Docs
+on:
+  push:
+    branches: [aci.documentation]
+permissions:
+  contents: write
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+      - name: Install dependencies
+        run: |
+          pip install sphinx sphinx_rtd_theme
+          pip install -r requirements/docs.txt
+      - name: Sphinx build
+        run: |
+          sphinx-build docs _build
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/
+          force_orphan: true
diff --git a/docs/_diagrams/credential_management/course_certificate_awarded.dsl b/docs/_diagrams/credential_management/course_certificate_awarded.dsl
@@ -0,0 +1,54 @@
+/*
+ * This is a high level diagram visualizing how a Course credential is awarded to a learner between the monolith and
+ * the Credentials IDA. It is written using Structurizr DSL (https://structurizr.org/).
+ */
+workspace {
+    model {
+        learner = person "Learner" "A learner taking courses on an Open edX site"
+
+        group "edx-platform" {
+            grades_app = softwareSystem "Grades Django App"
+            certificates_app = softwareSystem "Certificates Django App"
+            credentials_lms_app = softwareSystem "Credentials (LMS) Django App"
+            programs_app = softwareSystem "Programs Django App"
+            celery = softwareSystem "Celery"
+            monolith_db = softwareSystem "edx-platform DB"
+        }
+
+        group "Credentials IDA" {
+            credentials_app = softwareSystem "Credentials Django App"
+            api_app = softwareSystem "API Django App"
+            credentials_db = softwareSystem "Credentials DB"
+            credentials_eb_consumer = softwareSystem "Credentials Event Bus Consumer"
+        }
+
+        event_bus = softwareSystem "Event Bus"
+
+        credentials_eb_consumer -> event_bus "Polling, listening for Course Certificate events"
+
+        learner -> grades_app "Earns passing grade in course"
+        grades_app -> certificates_app "Emits a `COURSE_GRADE_NOW_PASSED` signal"
+        certificates_app -> monolith_db "Award course certificate in LMS"
+        certificates_app -> event_bus "Publishes a `CERTIFICATE_CREATED` event"
+        certificates_app -> programs_app "Emits a `COURSE_CERT_CHANGED` signal"
+        programs_app -> celery "Queues a `award_course_certificate` task"
+        celery -> credentials_lms_app "Processes `award_course_certificate` task"
+        credentials_lms_app -> api_app "Makes API request to award a course certificate to learner"
+        api_app -> credentials_app "Processes API request"
+        credentials_eb_consumer -> credentials_app "Processes `CERTIFICATE_CREATED` event"
+        credentials_app -> credentials_db "Award (Course) Credential to learner"
+    }
+
+    views {
+        systemlandscape "SystemLandscape" {
+            include *
+            autoLayout lr
+        }
+
+        styles {
+            element "Person" {
+                shape Person
+            }
+        }
+    }
+}
diff --git a/docs/_diagrams/credential_management/course_certificate_revoked.dsl b/docs/_diagrams/credential_management/course_certificate_revoked.dsl
@@ -0,0 +1,54 @@
+/*
+ * This is a high level diagram visualizing how a Course credential is revoked from a learner between the monolith and
+ * the Credentials IDA. It is written using Structurizr DSL (https://structurizr.org/).
+ */
+workspace {
+    model {
+        learner = person "Learner" "A learner taking courses on an Open edX site"
+
+        group "edx-platform" {
+            grades_app = softwareSystem "Grades Django App"
+            certificates_app = softwareSystem "Certificates Django App"
+            credentials_lms_app = softwareSystem "Credentials (LMS) Django App"
+            programs_app = softwareSystem "Programs Django App"
+            celery = softwareSystem "Celery"
+            monolith_db = softwareSystem "edx-platform DB"
+        }
+
+        group "Credentials IDA" {
+            credentials_app = softwareSystem "Credentials Django App"
+            api_app = softwareSystem "API Django App"
+            credentials_db = softwareSystem "Credentials DB"
+            credentials_eb_consumer = softwareSystem "Credentials Event Bus Consumer"
+        }
+
+        event_bus = softwareSystem "Event Bus"
+
+        credentials_eb_consumer -> event_bus "Polling, listening for Course Certificate events"
+
+        learner -> grades_app "Learner no longer course"
+        grades_app -> certificates_app "Emits a `COURSE_GRADE_NOW_FAILED` signal"
+        certificates_app -> monolith_db "Revoke course certificate in LMS"
+        certificates_app -> event_bus "Publishes a `CERTIFICATE_REVOKED` event"
+        certificates_app -> programs_app "Emits a `COURSE_CERT_CHANGED` signal"
+        programs_app -> celery "Queues an `award_course_certificate` task (note inaccurate legacy name)"
+        celery -> credentials_lms_app "Processes the `award_course_certificate` task"
+        credentials_lms_app -> api_app "Makes API request to revoke a course certificate from learner"
+        api_app -> credentials_app "Processes API request"
+        credentials_eb_consumer -> credentials_app "Processes `CERTIFICATE_REVOKED` event"
+        credentials_app -> credentials_db "Revoke (Course) Credential from learner"
+    }
+
+    views {
+        systemlandscape "SystemLandscape" {
+            include *
+            autoLayout lr
+        }
+
+        styles {
+            element "Person" {
+                shape Person
+            }
+        }
+    }
+}
diff --git a/docs/_diagrams/credential_management/program_certificate_awarded.dsl b/docs/_diagrams/credential_management/program_certificate_awarded.dsl
@@ -0,0 +1,46 @@
+/*
+ * This is a high level diagram visualizing how a Program credential is awarded to a learner between the monolith and
+ * the Credentials IDA. It is written using Structurizr DSL (https://structurizr.org/).
+ */
+workspace {
+    model {
+        learner = person "Learner" "A learner taking courses on Open edX site"
+
+        group "edx-platform" {
+            grades_app = softwareSystem "Grades Django App"
+            certificates_app = softwareSystem "Certificates Django App"
+            credentials_lms_app = softwareSystem "Credentials (LMS) Django App"
+            programs_app = softwareSystem "Programs Django App"
+            celery = softwareSystem "Celery"
+        }
+
+        group "Credentials IDA" {
+            credentials_app = softwareSystem "Credentials Django App"
+            api_app = softwareSystem "API Django App"
+        }
+
+        event_bus = softwareSystem "Event Bus"
+
+        learner -> grades_app "Earns passing grade in final course of a program"
+        grades_app -> certificates_app "Emits a `COURSE_GRADE_NOW_PASSED` signal"
+        certificates_app -> programs_app "Emits a `COURSE_CERT_AWARDED` signal"
+        programs_app -> celery "Queues an `award_program_certificate` task"
+        celery -> credentials_lms_app "Processes `award_program_certificate` task"
+        credentials_lms_app -> api_app "Makes API request to award program certificate to learner"
+        api_app -> credentials_app "Issues Program Credential to learner"
+        credentials_app -> event_bus "Emits `PROGRAM_CERTIFICATE_AWARDED` event to the Event Bus"
+    }
+
+    views {
+        systemlandscape "SystemLandscape" {
+            include *
+            autoLayout lr
+        }
+
+        styles {
+            element "Person" {
+                shape Person
+            }
+        }
+    }
+}
diff --git a/docs/_diagrams/credential_management/program_certificate_revoked.dsl b/docs/_diagrams/credential_management/program_certificate_revoked.dsl
@@ -0,0 +1,46 @@
+/*
+ * This is a high level diagram visualizing how a Program credential is revoked from a learner between the monolith and
+ * the Credentials IDA. It is written using Structurizr DSL (https://structurizr.org/).
+ */
+workspace {
+    model {
+        learner = person "Learner" "A learner taking courses on Open edX site"
+
+        group "edx-platform" {
+            grades_app = softwareSystem "Grades Django App"
+            certificates_app = softwareSystem "Certificates Django App"
+            credentials_lms_app = softwareSystem "Credentials (LMS) Django App"
+            programs_app = softwareSystem "Programs Django App"
+            celery = softwareSystem "Celery"
+        }
+
+        group "Credentials IDA" {
+            credentials_app = softwareSystem "Credentials Django App"
+            api_app = softwareSystem "API Django App"
+        }
+
+        event_bus = softwareSystem "Event Bus"
+
+        learner -> grades_app "Learner no longer passing course in a Program"
+        grades_app -> certificates_app "Emits a `COURSE_GRADE_NOW_FAILED` signal"
+        certificates_app -> programs_app "Emits a `COURSE_CERT_REVOKED` signal"
+        programs_app -> celery "Queues a `revoke_program_certificate` task"
+        celery -> credentials_lms_app "Processes `revoke_program_certificates` task"
+        credentials_lms_app -> api_app "Makes API request to revoke program certificate from learner"
+        api_app -> credentials_app "Revokes Program Credential from learner"
+        credentials_app -> event_bus "Emits `PROGRAM_CERTIFICATE_REVOKED` event to the Event Bus"
+    }
+
+    views {
+        systemlandscape "SystemLandscape" {
+            include *
+            autoLayout lr
+        }
+
+        styles {
+            element "Person" {
+                shape Person
+            }
+        }
+    }
+}
diff --git a/docs/_diagrams/learner_record_mfe/learner_record_mfe.dsl b/docs/_diagrams/learner_record_mfe/learner_record_mfe.dsl
@@ -0,0 +1,43 @@
+/*
+ * This is a high level diagram visualizing how a learner can access their program records and how data is retreived.
+ * It is written using Structurizr DSL (https://structurizr.org/).
+ */
+workspace {
+    model {
+        learner = person "Learner" "Registered learner on Open edX site"
+
+        group "edx-platform LMS" {
+            program_dashboard = softwareSystem "Program Dashboard (Legacy FE)"
+        }
+
+        group "Credentials IDA" {
+            records_app = softwareSystem "Records Django App"
+        }
+
+        profile_mfe = softwareSystem "(User) Profile MFE"
+        lr_mfe = softwareSystem "Learner Record MFE"
+
+        learner -> program_dashboard "views their Program Dashboard"
+        learner -> profile_mfe "views their user Profile"
+
+        program_dashboard -> records_app "clicks `View Program Record` button"
+        profile_mfe -> records_app "clicks `View my Records` button"
+
+        records_app -> lr_mfe "Learner redirected to"
+        lr_mfe -> records_app "REST API call to"
+        lr_mfe -> learner "Renders program record info for"
+    }
+
+    views {
+        systemlandscape "SystemLandscape" {
+            include *
+            autoLayout lr
+        }
+
+        styles {
+            element "Person" {
+                shape Person
+            }
+        }
+    }
+}
diff --git a/docs/_diagrams/learner_record_mfe/learner_record_mfe_program_records.dsl b/docs/_diagrams/learner_record_mfe/learner_record_mfe_program_records.dsl
@@ -0,0 +1,40 @@
+/*
+ * This is a high level diagram visualizing how the system retrieves information about a learner's progress in a
+ * specific program. It is written using Structurizr DSL (https://structurizr.org/).
+ */
+workspace {
+    model {
+        learner = person "Learner" "Registered learner on Open edX site"
+
+        group "Credentials IDA" {
+            catalog_app = softwareSystem "Catalog Django App"
+            core_app = softwareSystem "Core Django App"
+            credentials_app = softwareSystem "Credentials Django App"
+            records_app = softwareSystem "Records Django App"
+        }
+
+        lr_mfe = softwareSystem "Learner Record MFE"
+
+        learner -> lr_mfe "clicks `View Program Record` button"
+        lr_mfe -> records_app "REST API to retrieve program progress data"
+        records_app -> core_app "retrieves user info"
+        records_app -> catalog_app "retrieves pathway info"
+        records_app -> credentials_app "retrieves credential info"
+        records_app -> records_app "retrieves grade and sharing info"
+        records_app -> lr_mfe "returns program record info"
+        lr_mfe -> learner "renders program record for"
+    }
+
+    views {
+        systemlandscape "SystemLandscape" {
+            include *
+            autoLayout lr
+        }
+
+        styles {
+            element "Person" {
+                shape Person
+            }
+        }
+    }
+}
diff --git a/docs/_diagrams/program_completion_emails/program_completion_email.dsl b/docs/_diagrams/program_completion_emails/program_completion_email.dsl
@@ -0,0 +1,38 @@
+/*
+ * This is a high level diagram visualizing when the Credentials IDA emits a "program completion email". It is written
+ * using Structurizr DSL (https://structurizr.org/).
+ */
+workspace {
+    model {
+        learner = person "Learner" "A learner taking courses on Open edX site"
+
+        lms = softwareSystem "edx-platform LMS"
+
+        group "Credentials IDA" {
+            credentials_app = softwareSystem "Credentials Django App"
+            api_app = softwareSystem "API Django App"
+            edx_ace = softwareSystem "edX ACE App"
+        }
+
+        learner -> lms "Earns passing grade in final course of a program"
+        lms -> api_app "Makes API request to award program certificate to learner"
+        api_app -> credentials_app "Issues Program Credential to learner"
+        credentials_app -> credentials_app "Determine if email should be sent based on Program completion"
+        credentials_app -> edx_ace "Personalizes email based on message template and config"
+        edx_ace -> learner "Sends congratulatory message to learner"
+
+    }
+
+    views {
+        systemlandscape "SystemLandscape" {
+            include *
+            autoLayout lr
+        }
+
+        styles {
+            element "Person" {
+                shape Person
+            }
+        }
+    }
+}
diff --git a/docs/_static/images/badges/badges-admin-penalty-rules.png b/docs/_static/images/badges/badges-admin-penalty-rules.png
diff --git a/docs/_static/images/course_certificate_awarded.png b/docs/_static/images/course_certificate_awarded.png
diff --git a/docs/_static/images/course_certificate_revoked.png b/docs/_static/images/course_certificate_revoked.png
diff --git a/docs/_static/images/learner_record_mfe_create_program_record_link.png b/docs/_static/images/learner_record_mfe_create_program_record_link.png
diff --git a/docs/_static/images/learner_record_mfe_diagram.png b/docs/_static/images/learner_record_mfe_diagram.png
diff --git a/docs/_static/images/learner_record_mfe_download_program_record.png b/docs/_static/images/learner_record_mfe_download_program_record.png
diff --git a/docs/_static/images/learner_record_mfe_program_record_diagram.png b/docs/_static/images/learner_record_mfe_program_record_diagram.png
diff --git a/docs/_static/images/learner_record_mfe_share_program_record.png b/docs/_static/images/learner_record_mfe_share_program_record.png
diff --git a/docs/_static/images/program_certificate_awarded.png b/docs/_static/images/program_certificate_awarded.png
diff --git a/docs/_static/images/program_certificate_revoked.png b/docs/_static/images/program_certificate_revoked.png
diff --git a/docs/_static/images/program_completion_email.png b/docs/_static/images/program_completion_email.png
diff --git a/docs/_static/images/screenshot_program_completion_email_django_admin.png b/docs/_static/images/screenshot_program_completion_email_django_admin.png
diff --git a/docs/_static/images/verifiable_credentials-admin-section.png b/docs/_static/images/verifiable_credentials-admin-section.png
diff --git a/docs/_static/images/verifiable_credentials-issuance-lines.png b/docs/_static/images/verifiable_credentials-issuance-lines.png
diff --git a/docs/_static/images/verifiable_credentials-issuance-sequence.png b/docs/_static/images/verifiable_credentials-issuance-sequence.png
diff --git a/docs/_static/images/verifiable_credentials-issuer-configuration.png b/docs/_static/images/verifiable_credentials-issuer-configuration.png
diff --git a/docs/_static/images/verifiable_credentials-lcw-accept-credential.png b/docs/_static/images/verifiable_credentials-lcw-accept-credential.png
diff --git a/docs/_static/images/verifiable_credentials-lcw-add-credential.png b/docs/_static/images/verifiable_credentials-lcw-add-credential.png
diff --git a/docs/_static/images/verifiable_credentials-lcw-credential-preview.png b/docs/_static/images/verifiable_credentials-lcw-credential-preview.png
diff --git a/docs/_static/images/verifiable_credentials-lcw-home-empty.png b/docs/_static/images/verifiable_credentials-lcw-home-empty.png
diff --git a/docs/_static/images/verifiable_credentials-lcw-qrcode-scanner.png b/docs/_static/images/verifiable_credentials-lcw-qrcode-scanner.png
diff --git a/docs/_static/images/verifiable_credentials-lcw-setup1.png b/docs/_static/images/verifiable_credentials-lcw-setup1.png
diff --git a/docs/_static/images/verifiable_credentials-lcw-setup2.png b/docs/_static/images/verifiable_credentials-lcw-setup2.png
diff --git a/docs/_static/images/verifiable_credentials-lcw-setup3.png b/docs/_static/images/verifiable_credentials-lcw-setup3.png
diff --git a/docs/_static/images/verifiable_credentials-lcw-share-public-link-created.png b/docs/_static/images/verifiable_credentials-lcw-share-public-link-created.png
diff --git a/docs/_static/images/verifiable_credentials-lcw-share-public-link.png b/docs/_static/images/verifiable_credentials-lcw-share-public-link.png
diff --git a/docs/_static/images/verifiable_credentials-lcw-share.png b/docs/_static/images/verifiable_credentials-lcw-share.png
diff --git a/docs/_static/images/verifiable_credentials-lcw-verification-status.png b/docs/_static/images/verifiable_credentials-lcw-verification-status.png
diff --git a/docs/_static/images/verifiable_credentials-learner-record-mfe.png b/docs/_static/images/verifiable_credentials-learner-record-mfe.png
diff --git a/docs/analytics.rst b/docs/analytics.rst
@@ -1,7 +1,7 @@
 Analytics
 =========
 
-The credentials IDA uses Segment.io to track events.  If you set the ``segment_key`` variable in your site_configuration, a variety of events (segment API calls) will be triggered when navigating through the UI.
+The Credentials IDA uses Segment.io to track events.  If you set the ``segment_key`` variable in your site_configuration, a variety of events (segment API calls) will be triggered when navigating through the UI.
 
 Analytics for legacy/template pages
 ===================================
@@ -22,7 +22,7 @@ For example (from ``templates/_actions.html``):
         <span class="fa fa-facebook" aria-hidden="true"></span>
         <span class="action-label">{% trans 'Share this certificate via Facebook' as tmsg %}{{ tmsg | htmlescape }}</span>
       </button>
-       
+
 
 Analytics for react pages
 =========================