Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] feat: [ACI-240] Badges documentation #48

Open
wants to merge 23 commits into
base: aci.main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
486a422
feat: add documentation publication
wowkalucky Nov 21, 2023
f3ed397
chore: switch to master configuration
wowkalucky Apr 17, 2024
ea5bb74
doc: describe badges main concepts
wowkalucky Nov 30, 2023
9cbeaf5
doc: rework quick start
wowkalucky Apr 17, 2024
f2298d6
fix: add new theme to requirements
wowkalucky Apr 17, 2024
7ebd8c4
fix: update Quick Start page
wowkalucky Apr 18, 2024
00aa563
feat: add Settings page
wowkalucky Apr 18, 2024
4faa353
doc: add event bus consumers section
wowkalucky Apr 19, 2024
a362009
doc: add Configuration page and Configuration examples
wowkalucky Apr 19, 2024
1fefce4
doc: add EXCEPT rules examples
wowkalucky Apr 22, 2024
f9c03ca
doc: mark not relevant pages for removal
wowkalucky Apr 22, 2024
fbddbf6
doc: update the Processing page
wowkalucky Apr 22, 2024
2f1d963
doc: add progress records visualization
wowkalucky Apr 22, 2024
365ab6b
docs: add EXCLUDED_KEY_PATHS option description
wowkalucky Apr 24, 2024
7609686
docs: add grouped requirements examples
wowkalucky Apr 24, 2024
68da22d
fix: grouped requirements examples
wowkalucky Apr 25, 2024
2eb7346
Merge branch 'aci.main' into aci.documentation
wowkalucky May 16, 2024
9421dee
doc: actualize requirement groups configuration
wowkalucky May 16, 2024
1458744
Merge branch 'aci.main' into aci.documentation
wowkalucky May 22, 2024
2624c76
docs: add penalties configuration
wowkalucky May 22, 2024
800039c
feat: the latest BA documentation updates
wowkalucky Jun 17, 2024
191e043
chore: updrade documentation to upstream version
wowkalucky Jun 17, 2024
6b72f93
chore: refactor Badges documentation index
wowkalucky Jun 17, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions .github/workflows/documentation.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
name: Docs
on:
push:
branches: [aci.documentation]
Comment on lines +2 to +4
Copy link

@justinhynes justinhynes Jan 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will this eventually be carried over to the Credentials project for the master branch? Or is this just temporary for this feature branch/fork?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nope. It's temporary, just for internal convenience.

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
Original file line number Diff line number Diff line change
@@ -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
}
}
}
}
Original file line number Diff line number Diff line change
@@ -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
}
}
}
}
Original file line number Diff line number Diff line change
@@ -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
}
}
}
}
Original file line number Diff line number Diff line change
@@ -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
}
}
}
}
43 changes: 43 additions & 0 deletions docs/_diagrams/learner_record_mfe/learner_record_mfe.dsl
Original file line number Diff line number Diff line change
@@ -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
}
}
}
}
Original file line number Diff line number Diff line change
@@ -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
}
}
}
}
Original file line number Diff line number Diff line change
@@ -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
}
}
}
}
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/program_completion_email.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions docs/analytics.rst
Original file line number Diff line number Diff line change
@@ -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
===================================
Expand All @@ -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
=========================
Expand Down
Loading
Loading