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.

Sign up for GitHub

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

docs: update readme #10

Merged
merged 3 commits into from
Jun 22, 2023
+278 −232
Merged

docs: update readme #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2686846
docs: update readme
navinkarkera May 18, 2023
d826d47
chore: add authors file
navinkarkera May 19, 2023
e917d69
build: remove deprecated codecov package
navinkarkera Jun 14, 2023
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
2 changes: 2 additions & 0 deletions AUTHORS
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Navin Karkera <[email protected]>
Pooja Kulkarni <[email protected]>
133 changes: 104 additions & 29 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,112 @@
skill_tagging
#############################

.. note::

This README was auto-generated. Maintainer: please review its contents and
update all relevant sections. Instructions to you are marked with
"PLACEHOLDER" or "TODO". Update or remove those sections, and remove this
note when you are done.

|pypi-badge| |ci-badge| |codecov-badge| |doc-badge| |pyversions-badge|
|license-badge| |status-badge|

Purpose
*******
Overview
********

Django app for fetching and verifying tags/skills for video and vertical/unit
XBlocks. It implements two openedx_filters pipelines to inject a form into the end
unit XBlocks and video XBlocks.

Django app plugin for fetching and verifying tags for xblock skills.
.. image:: https://user-images.githubusercontent.com/10894099/210078679-3cbac3d1-55a7-4fba-b841-7fb4468f32c5.png
:target: https://user-images.githubusercontent.com/10894099/210078679-3cbac3d1-55a7-4fba-b841-7fb4468f32c5.png
:alt: vertical block verification form

.. image:: https://user-images.githubusercontent.com/10894099/212285572-efa5cfd5-e9c5-411d-8d15-541c43445ec0.png
:target: https://user-images.githubusercontent.com/10894099/212285572-efa5cfd5-e9c5-411d-8d15-541c43445ec0.png
:alt: video block verification form

More information about the XBlock skill tagging design can be found in this
`ADR`_.

.. _ADR: https://github.com/openedx/taxonomy-connector/blob/master/docs/decisions/0001-xblock-skill-tagging-design.rst

Set ``SHOW_SKILL_VERIFICATION_PROBABILITY`` in your django settings to configure
probability of displaying verification form. Values in range 0 to 1 are
allowed, where 0 means never and 1 means always display. Default value is 0.5
i.e. 50% chance of displaying the form.

Getting Started
***************

To install ``skill_tagging`` in `edx-platform`_, run

.. code-block::

pip install skill_tagging
navinkarkera marked this conversation as resolved.
Show resolved Hide resolved
navinkarkera marked this conversation as resolved.
Show resolved Hide resolved

# to install a development version locally in devstack
# clone this repo in `<devstack_base_dir>/src` directory and run
pip install -e /edx/src/xblock-skill-tagging

.. _edx-platform: https://github.com/openedx/edx-platform

This repo depends on discovery service for fetching skills/tags for a given
XBlock which depends on `taxonomy-connector`_ plugin for generating and serving these
tags. Setup ``taxonomy-connector`` plugin in `course-discovery`_ by installing it
via pip:

.. code-block::

pip install taxonomy-connector
navinkarkera marked this conversation as resolved.
Show resolved Hide resolved
navinkarkera marked this conversation as resolved.
Show resolved Hide resolved

# to install a development version locally in devstack
# clone this repo in `<devstack_base_dir>/src` directory and run
pip install -e /edx/src/taxonomy_connector

.. _taxonomy-connector: https://github.com/openedx/taxonomy-connector
.. _course-discovery: https://github.com/openedx/course-discovery

Whenever a user verifies tags/skills for an XBlock, ``skill_tagging`` `emits`_ an
openedx_event called ``XBLOCK_SKILL_VERIFIED``. This event needs to be consumed
navinkarkera marked this conversation as resolved.
Show resolved Hide resolved
by course discovery to make sure that the verification count is incremented for
that skill/tag.

To produce and consume this event, setup an implementation of event bus
like `event_bus_kafka`_ or `event_bus_redis`_. `How to start using the Event Bus`_
has detailed information on setting up event bus. The host would be
``edx-platform`` while ``course-discovery`` will be the consumer for the event
bus.

.. _emits: https://github.com/openedx/xblock-skill-tagging/blob/b323d8b13b66a69326b8fad77ccba4631dbdece9/skill_tagging/skill_tagging_mixin.py#L103
.. _event_bus_kafka: https://github.com/openedx/event-bus-kafka
.. _event_bus_redis: https://github.com/openedx/event-bus-redis
.. _How to start using the Event Bus: https://openedx.atlassian.net/wiki/spaces/AC/pages/3508699151/How+to+start+using+the+Event+Bus

Configuration
=============

Add following configuration values to the host django settings, i.e. LMS
settings: ``lms/envs/common.py``

.. code-block:: python

from .common import XBLOCK_MIXINS
# Below mixin adds the ability to fetch skills/tags from discovery and update them.
XBLOCK_MIXINS += ('skill_tagging.skill_tagging_mixin.SkillTaggingMixin',)
# Set below url to point to discovery service.
TAXONOMY_API_BASE_URL='http://edx.devstack.discovery:18381'
# Configure the maximum number skills/tags to display in the form for a given xblock.
TAXONOMY_API_SKILL_PAGE_SIZE=20
# Copy this as is, this configures the required openedx_filters.
OPEN_EDX_FILTERS_CONFIG = {
"org.openedx.learning.vertical_block.render.completed.v1": {
"fail_silently": False,
"pipeline": [
"skill_tagging.pipeline.AddVerticalBlockSkillVerificationSection",
]
},
"org.openedx.learning.vertical_block_child.render.started.v1": {
"fail_silently": False,
"pipeline": [
"skill_tagging.pipeline.AddVideoBlockSkillVerificationComponent",
]
}
}
# helps to configure probability of displaying the verification forms. Values in range 0 to 1 are allowed, where 0
# means never and 1 means always display. Default value is 0.5 i.e. 50% chance of displaying the form.
SHOW_SKILL_VERIFICATION_PROBABILITY = 0.5


Developing
==========

navinkarkera marked this conversation as resolved.
Show resolved Hide resolved
Expand Down Expand Up @@ -74,27 +157,19 @@ Every time you develop something in this repo

# Open a PR and ask for review.


Deploying
=========

TODO: How can a new user go about deploying this component? Is it just a few
Copy link
Contributor

Choose a reason for hiding this comment

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

Since this package is deployed to PyPI, it may still be helpful to note that here and say that it's automated and will happen for any new tags that get pushed to this repository.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Done.

commands? Is there a larger how-to that should be linked here?

PLACEHOLDER: For details on how to deploy this component, see the `deployment how-to`_

.. _deployment how-to: https://docs.openedx.org/projects/xblock-skill-tagging/how-tos/how-to-deploy-this-component.html
This package is automatically published to pypi whenever a new tag is pushed to the repository.

Getting Help
************

Documentation
=============

PLACEHOLDER: Start by going through `the documentation`_. If you need more help see below.
Copy link
Contributor

Choose a reason for hiding this comment

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

It's better to acknowledge that there is no published documentation than to omit this section all together.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Done.


.. _the documentation: https://docs.openedx.org/projects/xblock-skill-tagging

(TODO: `Set up documentation <https://openedx.atlassian.net/wiki/spaces/DOC/pages/21627535/Publish+Documentation+on+Read+the+Docs>`_)
Published documentation is not available.

More Help
=========
Expand Down Expand Up @@ -160,8 +235,8 @@ Reporting Security Issues

Please do not report security issues in public. Please email [email protected].

.. |pypi-badge| image:: https://img.shields.io/pypi/v/xblock-skill-tagging.svg
:target: https://pypi.python.org/pypi/xblock-skill-tagging/
.. |pypi-badge| image:: https://img.shields.io/pypi/v/skill_tagging.svg
:target: https://pypi.python.org/pypi/skill_tagging/
:alt: PyPI

.. |ci-badge| image:: https://github.com/openedx/xblock-skill-tagging/workflows/Python%20CI/badge.svg?branch=main
Expand All @@ -176,8 +251,8 @@ Please do not report security issues in public. Please email [email protected].
:target: https://xblock-skill-tagging.readthedocs.io/en/latest/
:alt: Documentation

.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/xblock-skill-tagging.svg
:target: https://pypi.python.org/pypi/xblock-skill-tagging/
.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/skill_tagging.svg
:target: https://pypi.python.org/pypi/skill_tagging/
:alt: Supported Python versions

.. |license-badge| image:: https://img.shields.io/github/license/openedx/xblock-skill-tagging.svg
Expand Down
20 changes: 11 additions & 9 deletions requirements/base.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@
#
# make upgrade
#
asgiref==3.6.0
asgiref==3.7.2
# via django
attrs==22.2.0
attrs==23.1.0
# via openedx-events
django==3.2.18
django==3.2.19
# via
# -c https://raw.githubusercontent.com/edx/edx-lint/master/edx_lint/files/common_constraints.txt
# -r requirements/base.in
Expand All @@ -19,19 +19,21 @@ django-model-utils==4.3.1
# via -r requirements/base.in
edx-opaque-keys[django]==2.3.0
# via openedx-events
fastavro==1.7.1
fastavro==1.7.4
# via openedx-events
openedx-events==5.1.0
openedx-events==8.0.1
# via -r requirements/base.in
openedx-filters==1.1.0
openedx-filters==1.3.0
# via -r requirements/base.in
pbr==5.11.1
# via stevedore
pymongo==3.13.0
# via edx-opaque-keys
pytz==2022.7.1
pytz==2023.3
# via django
sqlparse==0.4.3
sqlparse==0.4.4
# via django
stevedore==5.0.0
stevedore==5.1.0
# via edx-opaque-keys
typing-extensions==4.6.3
# via asgiref
1 change: 0 additions & 1 deletion requirements/ci.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,5 @@

-c constraints.txt

codecov # Code coverage reporting
tox # Virtualenv management for tests
tox-battery # Makes tox aware of requirements file changes
22 changes: 4 additions & 18 deletions requirements/ci.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,32 +4,20 @@
#
# make upgrade
#
certifi==2022.12.7
# via requests
charset-normalizer==3.0.1
# via requests
codecov==2.1.12
# via -r requirements/ci.in
coverage==7.1.0
# via codecov
distlib==0.3.6
# via virtualenv
filelock==3.9.0
filelock==3.12.2
# via
# tox
# virtualenv
idna==3.4
# via requests
packaging==23.0
packaging==23.1
# via tox
platformdirs==3.0.0
platformdirs==3.5.3
# via virtualenv
pluggy==1.0.0
# via tox
py==1.11.0
# via tox
requests==2.28.2
# via codecov
six==1.16.0
# via tox
tomli==2.0.1
Expand All @@ -41,7 +29,5 @@ tox==3.28.0
# tox-battery
tox-battery==0.6.1
# via -r requirements/ci.in
urllib3==1.26.14
# via requests
virtualenv==20.19.0
virtualenv==20.23.0
# via tox
Loading