docs: convert readme from .md to .rst
With a few minor corrections. Signed-off-by: Anton Melser <anton.melser@outlook.com>
This commit is contained in:
Anton Melser
committed by
Farhaan Bukhsh
Farhaan Bukhsh
parent
45e81aff46
commit
81aa35edd6
189
README.md
189
README.md
@@ -1,189 +0,0 @@
|
||||
# frontend-app-gradebook
|
||||
|
||||
[](https://travis-ci.com/edx/frontend-app-gradebook)
|
||||
[](https://app.codecov.io/gh/openedx/frontend-app-gradebook)
|
||||
[](@edx/frontend-app-gradebook)
|
||||
[](@edx/frontend-app-gradebook)
|
||||
[](@edx/frontend-app-gradebook)
|
||||
[](https://github.com/semantic-release/semantic-release)
|
||||
|
||||
# Purpose
|
||||
|
||||
Gradebook allows course staff to view, filter, and override subsection grades for a course. Additionally for Masters courses, Gradebook enables bulk management of subsection grades.
|
||||
|
||||
Jump to:
|
||||
|
||||
- [Should I use Gradebook in my course?](#should-i-use-gradebook-in-my-course)
|
||||
- [Quickstart](#quickstart)
|
||||
|
||||
For existing documentation see:
|
||||
|
||||
- Basic Usage: [Review Learner Grades (read-the-docs)](https://docs.openedx.org/en/latest/educators/how-tos/data/view_learner_grades.html)
|
||||
- Bulk Grade Management: [Override Learner Subsection Scores in Bulk (read-the-docs)](https://docs.openedx.org/en/latest/educators/how-tos/data/manage_learner_grades.html#override-learner-subsection-scores-in-bulk)
|
||||
|
||||
## Should I use Gradebook in my course?
|
||||
|
||||
### What does this offer over the legacy gradebook?
|
||||
|
||||
The micro-frontend offers a great deal more granularity when searching for problems, an easy interface for editing grades, an
|
||||
audit trail for seeing who edited what grade and what reason they gave (if any) for doing so.
|
||||
|
||||
UsageProblems can be filtered by student as in the traditional gradebook, but can also be filtered by scores to see who
|
||||
scored within a certain range, and by assignment types (note: Not problem types, but categories like ‘Exams’ or
|
||||
‘Homework’).
|
||||
|
||||
### What does the legacy gradebook offer that this project does not?
|
||||
|
||||
This project does not (yet, at least) create any graphs, which the traditional gradebook does. It also does not give
|
||||
quick links to the problems for the instructor to visit. It expects the instructor to be familiar with the problems they
|
||||
are grading and which unit they refer to.
|
||||
|
||||
The gradebook is expected to be much more performant for larger numbers of students as well. The Instructor Dashboard
|
||||
link for the legacy gradebook reports that "this feature is available only to courses with a small number of enrolled
|
||||
learners." However, this project comes with no such warning.
|
||||
|
||||
### Who should not change to this gradebook?
|
||||
|
||||
Groups whose instructors need not ever manually override grades do not need this project, but may not be any worse off
|
||||
depending on their needs. Instructors that expect to review grades infrequently enough that not having a direct link
|
||||
to the problem in question will have a worse UX than the legacy gradebook provides. Instructors that rely on the graphs
|
||||
generated by the current gradebook might find the lack of autogenerated graphs to be frustrating.
|
||||
|
||||
## Getting Started
|
||||
|
||||
|
||||
### Installation
|
||||
|
||||
To install gradebook into your project:
|
||||
```
|
||||
npm i --save @edx/frontend-app-gradebook
|
||||
```
|
||||
|
||||
Cloning and Startup
|
||||
===================
|
||||
|
||||
1. Clone your new repo:
|
||||
|
||||
``git clone https://github.com/openedx/frontend-app-gradebook.git``
|
||||
|
||||
2. Use the version of Node specified in ``.nvmrc``
|
||||
|
||||
3. Stop the Tutor devstack, if it's running:
|
||||
|
||||
``tutor dev stop``
|
||||
|
||||
4. Next, we need to tell Tutor that we're going to be running this repo in development mode, and it should be excluded from the mfe container that otherwise runs every MFE. Run this:
|
||||
|
||||
``tutor mounts add /path/to/frontend-app-gradebook``
|
||||
|
||||
5. Start Tutor in development mode. This command will start the LMS and Studio,
|
||||
and other required MFEs like ``authn`` and ``account``, but will not start the
|
||||
Gradebook MFE, which we're going to run on the host instead of in a container
|
||||
managed by Tutor. Run:
|
||||
|
||||
``tutor dev start lms cms mfe``
|
||||
|
||||
## Startup
|
||||
|
||||
1. Install npm dependencies:
|
||||
|
||||
``cd frontend-app-gradebook && npm install``
|
||||
|
||||
2. Start the dev server:
|
||||
|
||||
``npm run dev``
|
||||
|
||||
## Running the UI Standalone
|
||||
|
||||
To install the project please refer to the [`MFE Development on Tutor`](https://github.com/overhangio/tutor-mfe?tab=readme-ov-file#mfe-development) instructions.
|
||||
|
||||
When not mounted, gradebook will run in the shared MFE container at http://apps.local.openedx.io/gradebook/course-v1:edX+DemoX+Demo_Course.
|
||||
|
||||
When mounted in the tutor ``gradebook`` container, or when running a local (host) webpack dev server, the web application runs on port **1994**, so when you go to `http://apps.local.openedx.io:1994/gradebook/course-v1:edX+DemoX+Demo_Course` you should see the UI (assuming you have such a Demo Course in your devstack). Note that you always have to provide a course id to actually see a gradebook.
|
||||
|
||||
(Note: This may not work in Tutor; these instructions are for the deprecated Devstack) You can see the log messages for the docker container by executing `make gradebook-logs` in the `devstack` directory.
|
||||
|
||||
Note that starting the container executes the `npm run start` script which will hot-reload JavaScript and Sass files changes, so you should (:crossed_fingers:) not need to do anything (other than wait) when making changes.
|
||||
|
||||
## Plugins
|
||||
This MFE can be customized using [Frontend Plugin Framework](https://github.com/openedx/frontend-plugin-framework).
|
||||
|
||||
The parts of this MFE that can be customized in that manner are documented [here](/src/plugin-slots).
|
||||
|
||||
## Running tests
|
||||
|
||||
Run:
|
||||
|
||||
``nvm use``
|
||||
|
||||
``npm ci``
|
||||
|
||||
``npm test``
|
||||
|
||||
## Directory Structure
|
||||
|
||||
* `config`
|
||||
* Directory for [`webpack`](https://webpack.js.org/) configurations
|
||||
* `public`
|
||||
* Entry point for the single-page application - `gradebook` has a single `index.html` file
|
||||
* `src`
|
||||
* `components`
|
||||
* Directory for presentational `React` components
|
||||
* `containers`
|
||||
* Directory for container `React` components
|
||||
* `data`
|
||||
* `actions`
|
||||
* Directory for `Redux` action creators
|
||||
* `constants`
|
||||
* `reducers`
|
||||
* Directory for `Redux` reducers
|
||||
|
||||
## Authentication with backend API services
|
||||
|
||||
See the [`@edx/frontend-auth`](https://github.com/edx-unsupported/frontend-auth) repo for information about securing routes in your application that require user authentication.
|
||||
|
||||
License
|
||||
=======
|
||||
|
||||
The code in this repository is licensed under the AGPLv3 unless otherwise
|
||||
noted.
|
||||
|
||||
Contributing
|
||||
============
|
||||
|
||||
Contributions are very welcome. Please read [How To Contribute](https://docs.openedx.org/en/latest/developers/references/developer_guide/process/index.html) for details.
|
||||
|
||||
This project is currently accepting all types of contributions, bug fixes,
|
||||
security fixes, maintenance work, or new features. However, please make sure
|
||||
to have a discussion about your new feature idea with the maintainers prior to
|
||||
beginning development to maximize the chances of your change being accepted.
|
||||
You can start a conversation by creating a new issue on this repo summarizing
|
||||
your idea.
|
||||
|
||||
Getting Help
|
||||
===========
|
||||
|
||||
If you're having trouble, we have discussion forums at
|
||||
https://discuss.openedx.org where you can connect with others in the community.
|
||||
|
||||
Our real-time conversations are on Slack. You can request a [Slack
|
||||
invitation](https://openedx.org/slack), then join our
|
||||
[community Slack workspace](https://openedx.slack.com/) Because this is a
|
||||
frontend repository, the best place to discuss it would be in the
|
||||
[#wg-frontend channel](https://openedx.slack.com/archives/C04BM6YC7A6).
|
||||
|
||||
For anything non-trivial, the best path is to open an issue in this repository
|
||||
with as many details about the issue you are facing as you can provide.
|
||||
|
||||
https://github.com/openedx/frontend-app-gradebook/issues
|
||||
|
||||
For more information about these options, see the [Getting Help](https://openedx.org/community/connect) page.
|
||||
|
||||
The Open edX Code of Conduct
|
||||
============================
|
||||
|
||||
All community members are expected to follow the [Open edX Code of Conduct](https://openedx.org/code-of-conduct/).
|
||||
|
||||
Reporting Security Issues
|
||||
=========================
|
||||
Please do not report security issues in public. Please email security@openedx.org.
|
||||
253
README.rst
Normal file
253
README.rst
Normal file
@@ -0,0 +1,253 @@
|
||||
frontend-app-gradebook
|
||||
#######################
|
||||
|
||||
|Build Status| |Codecov| |npm_version| |npm_downloads| |license| |semantic-release|
|
||||
|
||||
Purpose
|
||||
*******
|
||||
|
||||
Gradebook allows course staff to view, filter, and override subsection grades for a course. Additionally for Masters courses, Gradebook enables bulk management of subsection grades.
|
||||
|
||||
Jump to:
|
||||
|
||||
- `Should I use Gradebook in my course?`_
|
||||
- Quickstart_
|
||||
|
||||
For existing documentation see:
|
||||
|
||||
- Basic Usage: `Review Learner Grades (read-the-docs) <https://docs.openedx.org/en/latest/educators/how-tos/data/view_learner_grades.html>`_
|
||||
- Bulk Grade Management: `Override Learner Subsection Scores in Bulk (read-the-docs) <https://docs.openedx.org/en/latest/educators/how-tos/data/manage_learner_grades.html#override-learner-subsection-scores-in-bulk>`_
|
||||
|
||||
Should I use Gradebook in my course?
|
||||
*************************************
|
||||
|
||||
What does this offer over the legacy gradebook?
|
||||
================================================
|
||||
|
||||
The micro-frontend offers a great deal more granularity when searching for problems, an easy interface for editing grades, an
|
||||
audit trail for seeing who edited what grade and what reason they gave (if any) for doing so.
|
||||
|
||||
UsageProblems can be filtered by student as in the traditional gradebook, but can also be filtered by scores to see who
|
||||
scored within a certain range, and by assignment types (note: Not problem types, but categories like 'Exams' or
|
||||
'Homework').
|
||||
|
||||
What does the legacy gradebook offer that this project does not?
|
||||
=================================================================
|
||||
|
||||
This project does not (yet, at least) create any graphs, which the traditional gradebook does. It also does not give
|
||||
quick links to the problems for the instructor to visit. It expects the instructor to be familiar with the problems they
|
||||
are grading and which unit they refer to.
|
||||
|
||||
The gradebook is expected to be much more performant for larger numbers of students as well. The Instructor Dashboard
|
||||
link for the legacy gradebook reports that "this feature is available only to courses with a small number of enrolled
|
||||
learners." However, this project comes with no such warning.
|
||||
|
||||
Who should not change to this gradebook?
|
||||
=========================================
|
||||
|
||||
Groups whose instructors need not ever manually override grades do not need this project, but may not be any worse off
|
||||
depending on their needs. Instructors that expect to review grades infrequently enough that not having a direct link
|
||||
to the problem in question will have a worse UX than the legacy gradebook provides. Instructors that rely on the graphs
|
||||
generated by the current gradebook might find the lack of autogenerated graphs to be frustrating.
|
||||
|
||||
Getting Started
|
||||
***************
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
To install gradebook into your project:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
npm i --save @edx/frontend-app-gradebook
|
||||
|
||||
Quickstart
|
||||
==========
|
||||
|
||||
Cloning and Setup
|
||||
-----------------
|
||||
|
||||
1. Clone your new repo:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git clone https://github.com/openedx/frontend-app-gradebook.git
|
||||
|
||||
2. Use the version of Node specified in ``.nvmrc``
|
||||
|
||||
3. Stop the Tutor devstack, if it's running:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
tutor dev stop
|
||||
|
||||
4. Next, we need to tell Tutor that we're going to be running this repo in development mode, and it should be excluded from the mfe container that otherwise runs every MFE. Run this:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
tutor mounts add /path/to/frontend-app-gradebook
|
||||
|
||||
5. Start Tutor in development mode. This command will start the LMS and Studio,
|
||||
and other required MFEs like ``authn`` and ``account``, but will not start the
|
||||
Gradebook MFE, which we're going to run on the host instead of in a container
|
||||
managed by Tutor. Run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
tutor dev start lms cms mfe
|
||||
|
||||
Startup
|
||||
-------
|
||||
|
||||
1. Install npm dependencies:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd frontend-app-gradebook && npm install
|
||||
|
||||
2. Start the dev server:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
npm run dev
|
||||
|
||||
Running the UI Standalone
|
||||
==========================
|
||||
|
||||
To install the project please refer to the `MFE Development on Tutor <https://github.com/overhangio/tutor-mfe?tab=readme-ov-file#mfe-development>`_ instructions.
|
||||
|
||||
When not mounted, gradebook will run in the shared MFE container at http://apps.local.openedx.io/gradebook/course-v1:edX+DemoX+Demo_Course.
|
||||
|
||||
When mounted in the tutor ``gradebook`` container, or when running a local (host) webpack dev server, the web application runs on port **1994**, so when you go to http://apps.local.openedx.io:1994/gradebook/course-v1:edX+DemoX+Demo_Course you should see the UI (assuming you have such a Demo Course in your devstack). Note that you always have to provide a course id to actually see a gradebook.
|
||||
|
||||
(Note: This may not work in Tutor; these instructions are for the deprecated Devstack) You can see the log messages for the docker container by executing ``make gradebook-logs`` in the ``devstack`` directory.
|
||||
|
||||
Note that starting the container executes the ``npm run start`` script which will hot-reload JavaScript and Sass files changes, so you should (:crossed_fingers:) not need to do anything (other than wait) when making changes.
|
||||
|
||||
Plugins
|
||||
*******
|
||||
|
||||
This MFE can be customized using `Frontend Plugin Framework <https://github.com/openedx/frontend-plugin-framework>`_.
|
||||
|
||||
The parts of this MFE that can be customized in that manner are documented `here </src/plugin-slots>`_.
|
||||
|
||||
Running tests
|
||||
*************
|
||||
|
||||
Run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
nvm use
|
||||
|
||||
npm ci
|
||||
|
||||
npm test
|
||||
|
||||
Directory Structure
|
||||
*******************
|
||||
|
||||
* ``config``
|
||||
|
||||
* Directory for `webpack <https://webpack.js.org/>`_ configurations
|
||||
|
||||
* ``public``
|
||||
|
||||
* Entry point for the single-page application - ``gradebook`` has a single ``index.html`` file
|
||||
|
||||
* ``src``
|
||||
|
||||
* ``components``
|
||||
|
||||
* Directory for presentational ``React`` components
|
||||
|
||||
* ``containers``
|
||||
|
||||
* Directory for container ``React`` components
|
||||
|
||||
* ``data``
|
||||
|
||||
* ``actions``
|
||||
|
||||
* Directory for ``Redux`` action creators
|
||||
|
||||
* ``constants``
|
||||
* ``reducers``
|
||||
|
||||
* Directory for ``Redux`` reducers
|
||||
|
||||
Authentication with backend API services
|
||||
*****************************************
|
||||
|
||||
See the `@edx/frontend-auth <https://github.com/edx-unsupported/frontend-auth>`_ repo for information about securing routes in your application that require user authentication.
|
||||
|
||||
License
|
||||
*******
|
||||
|
||||
The code in this repository is licensed under the AGPLv3 unless otherwise
|
||||
noted.
|
||||
|
||||
Please see `LICENSE <LICENSE>`_ for details.
|
||||
|
||||
Contributing
|
||||
************
|
||||
|
||||
Contributions are very welcome. Please read `How To Contribute`_ for details.
|
||||
|
||||
.. _How To Contribute: https://openedx.org/r/how-to-contribute
|
||||
|
||||
This project is currently accepting all types of contributions, bug fixes,
|
||||
security fixes, maintenance work, or new features. However, please make sure
|
||||
to have a discussion about your new feature idea with the maintainers prior to
|
||||
beginning development to maximize the chances of your change being accepted.
|
||||
You can start a conversation by creating a new issue on this repo summarizing
|
||||
your idea.
|
||||
|
||||
Getting Help
|
||||
************
|
||||
|
||||
If you're having trouble, we have discussion forums at
|
||||
https://discuss.openedx.org where you can connect with others in the community.
|
||||
|
||||
Our real-time conversations are on Slack. You can request a `Slack
|
||||
invitation`_, then join our `community Slack workspace`_. Because this is a
|
||||
frontend repository, the best place to discuss it would be in the
|
||||
`#wg-frontend channel`_.
|
||||
|
||||
For anything non-trivial, the best path is to open an issue in this repository
|
||||
with as many details about the issue you are facing as you can provide.
|
||||
|
||||
https://github.com/openedx/frontend-app-gradebook/issues
|
||||
|
||||
For more information about these options, see the `Getting Help`_ page.
|
||||
|
||||
.. _Slack invitation: https://openedx.org/slack
|
||||
.. _community Slack workspace: https://openedx.slack.com/
|
||||
.. _#wg-frontend channel: https://openedx.slack.com/archives/C04BM6YC7A6
|
||||
.. _Getting Help: https://openedx.org/community/connect
|
||||
|
||||
The Open edX Code of Conduct
|
||||
*****************************
|
||||
|
||||
All community members are expected to follow the `Open edX Code of Conduct`_.
|
||||
|
||||
.. _Open edX Code of Conduct: https://openedx.org/code-of-conduct/
|
||||
|
||||
Reporting Security Issues
|
||||
**************************
|
||||
|
||||
Please do not report security issues in public. Please email security@openedx.org.
|
||||
|
||||
.. |Build Status| image:: https://api.travis-ci.com/edx/frontend-app-gradebook.svg?branch=master
|
||||
:target: https://travis-ci.com/edx/frontend-app-gradebook
|
||||
.. |Codecov| image:: https://img.shields.io/codecov/c/gh/openedx/frontend-app-gradebook
|
||||
:target: https://app.codecov.io/gh/openedx/frontend-app-gradebook
|
||||
.. |npm_version| image:: https://img.shields.io/npm/v/@edx/frontend-app-gradebook.svg
|
||||
:target: @edx/frontend-app-gradebook
|
||||
.. |npm_downloads| image:: https://img.shields.io/npm/dt/@edx/frontend-app-gradebook.svg
|
||||
:target: @edx/frontend-app-gradebook
|
||||
.. |license| image:: https://img.shields.io/npm/l/@edx/frontend-app-gradebook.svg
|
||||
:target: @edx/frontend-app-gradebook
|
||||
.. |semantic-release| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
|
||||
:target: https://github.com/semantic-release/semantic-release
|
||||
Reference in New Issue
Block a user