Update documentation

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 0bd13fe87530f01595e010e46b7ef608
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/authentication.rst.txt

@@ -0,0 +1,4 @@
+Authentication
+==============
+
+.. mermaid:: assets/authentication-flow.mm

_sources/commands/check_program_requirements.rst.txt

@@ -0,0 +1,22 @@
+``check_program_requirements``
+==============================
+
+Checks programs for a valid requirements tree. A program has a valid requirements tree if it:
+
+1. Exists
+2. Has nodes for all courses assigned to the program
+
+If the tree does not fit this criteria, an error message is printed to the screen. (This uses the ``check_program_for_orphans`` API call, but it suppresses its error logging so it won't clog up the error log.)
+
+By default, this will check all programs in the system. Specify individual programs to check with ``--program`` (multiple times if needed) or check only live programs with ``--live``. Note that if you specify both of these together they will be combined: if you specify a check for a specific program that isn't live and then also specify ``--live``, it won't return anything for that program.
+
+Syntax
+------
+
+``check_program_requirements [--program <readable or numeric id>] [--live]``
+
+Options
+-------
+
+* ``--program <readable or numeric id>`` - Check this specific program. Can be either the readable ID of the program (e.g. ``program-v1:MITx+DEDP``) or the numeric ID, and can be specified multiple times to check multiple programs.
+* ``--live`` - Check only live programs.

_sources/commands/configure_instance.rst.txt

@@ -0,0 +1,23 @@
+``configure_instance``
+======================
+
+Configures a fresh MITx Online instance. For more information, see :doc:`MITx Online Quick Start<../configuration/quickstart>` and :doc:`Local Open edX Tutor and MITx Online Deployment<../configuration/tutor>`.
+
+For Tutor deployments, this will use ``local.edly.io`` for URLs for the edX platform. If you're running a dev deployment, or are using Tutor Nightly, ``--tutor-dev`` will additionally add the proper ports (as Caddy is disabled in these cases). In either case, the two demo courses will still be created but only the Demonstration Course (``course-v1:edX+DemoX+Demo_Course``) will exist in edX, and then only if you import the demo course using the relevant Tutor command.
+
+Syntax
+------
+
+``configure_instance <platform> [--dont-enroll|-D] [--dont-create-superuser|-S] [--edx-oauth-client <client id>] [--edx-oauth-secret <client secret>] [--gateway <ip>] [--tutor|-T] [--tutor-dev]``
+
+Options
+-------
+
+* ``<platform>`` - One of ``macos``, ``linux``, or ``none``. Specifying ``none`` will additionaly stop creation of the OAuth2 application record for edX. Defaults to ``none``.
+* ``--dont-enroll|-D`` - Don't enroll the test learner account in any courses. (Defaults to enrolling the account in ``course-v1:edX+DemoX+Demo_Course``.)
+* ``--dont-create-superuser|-S`` - Don't create a superuser account.
+* ``--gateway <ip>`` - The Docker gateway IP. Required on Linux. See :doc:`Configure Open edX<../configuration/open_edx>` for more info.
+* ``--edx-oauth-client <client id>`` - Use the specified client ID for the edX OAuth2 client. (Useful if you're redoing your MITx Online instance and you've already created the corresponding record in edX, since you're not allowed to edit it there.)
+* ``--edx-oauth-secret <client secret>`` - Use the specified client secret for the edX OAuth2 client. (Useful if you're redoing your MITx Online instance and you've already created the corresponding record in edX, since you're not allowed to edit it there.)
+* ``--tutor|-T`` - Configure the instance for use with a Tutor edX deployment.
+* ``--tutor-dev`` - Configure the instnace for use with Tutor dev or nightly.

_sources/commands/configure_tiers.rst.txt

@@ -0,0 +1,86 @@
+``configure_tiers``
+===================
+
+Creates financial assistance tiers and discounts for a course or program.
+
+This operates in two modes: creating tiers for a program and creating tiers for a course.
+
+*In the tables below, <year> represents the current year.*
+
+**Configuring tiers for a course**
+
+The command will use the readable ID of the course as part of the financial aid discounts. They will default to this:
+
+=========================== ============= ======
+Code                        Type          Amount
+=========================== ============= ======
+<course id>-fa-tier1-<year> percent-off   .75
+<course id>-fa-tier2-<year> percent-off   .50
+<course id>-fa-tier3-<year> percent-off   .25
+<course id>-fa-tier4-<year> percent-off   0
+=========================== ============= ======
+
+Note that configuring course tiers requires the course to exist. Use ``create_courseware`` (or any of the other methods) to create the course before you run this command.
+
+**Configuring tiers for a program**
+
+The default discounts will be:
+
+==================== =========== ======
+Code                 Type        Amount
+==================== =========== ======
+DEDP-fa-tier1-<year> dollars-off 750
+DEDP-fa-tier2-<year> dollars-off 650
+DEDP-fa-tier3-<year> dollars-off 500
+DEDP-fa-tier4-<year> percent-off 0
+==================== =========== ======
+
+Specify changes using ``--program`` and/or ``--program-abbrev``.
+
+**Tiers**
+
+The actual tiers that will be created are:
+
+========= ========================
+Threshold Discount
+========= ========================
+$0        <abbrev>-fa-tier1-<year>
+$25,000   <abbrev>-fa-tier2-<year>
+$50,000   <abbrev>-fa-tier3-<year>
+$75,000   <abbrev>-fa-tier4-<year>
+========= ========================
+
+These can be overridden by providing a CSV file. The CSV file should have the following fields and should not have a header row::
+
+  threshold amount,discount type,discount amount
+
+If you specify tier information, you must provide all the tiers you want to create - the specified information will override the default. In addition, you must supply a zero income tier. This is a requirement and the command will quit if you don't have one set up, as that tier is used as the starting point for financial assistance. (In other words, learners will see errors if there's not a zero-income threshold tier set up.)
+
+**Reuse**
+
+The command will try to reuse any discounts and tiers that match ones the command would have created, so you can safely run this for a course or program that may have already had financial assistance tiers set up.
+
+Syntax
+------
+
+Configuring tiers for a program:
+``configure_tiers [--program <readable id>] [--program-abbrev <program abbreviation>] [--tier-info <tier info CSV>]``
+
+Configuring tiers for a course:
+``configure_tiers [--course <readable id>] [--tier-info <tier info CSV>]``
+
+Options
+-------
+
+Program options:
+
+* ``--program <readable id>`` - Program ID to use or create.
+* ``--program-abbrev <abbreviation>`` - Abbreviation to use for tiers and discounts.
+
+Course options:
+
+* ``--course <readable id>`` - Course ID to use. This won't create a course; use ``create_courseware`` for that.
+
+Common options:
+
+* ``--tier-info <csv file>`` - Tier info in CSV format.

_sources/commands/create_courseware.rst.txt

@@ -0,0 +1,60 @@
+``create_courseware``
+=====================
+
+Creates a new courseware object.
+
+**For programs**, this creates the basic program record.
+**For courses**, this creates the course, and then optionally adds it to the specified program (and can add it as an elective or required course). It will also optionally create an initial course run for the course. Finally, it will also add the course to the program's requirements or electives list.
+**For courseruns**, this creates the course run and associates it with the specified course.
+
+This will not run ``sync_course_run`` for you, so for best results, ensure the course run is set up on the edX side, use this command, then run ``sync_course_run`` to pull dates and other information from edX.
+
+Syntax
+------
+
+``create_courseware <object> <readable id> <title> [--live] [--self-paced] [--create-run [create_run]] [--run-url [RUN_URL]] [--program [PROGRAM]] [--run-tag [run-tag]] [--required] [--elective] [--force] [--start <date>] [--end <date>] [--enrollment-start <date>] [--enrollment-end <date>] [--upgrade <date>] [--dept <department_name>] [--create-depts]``
+
+Checks
+------
+
+The command performs the following checks:
+* It checks to see if ``readable_id`` contains ``course`` or ``program`` at the front - if it doesn't, it will assume you've swapped the title and readable ID mistakenly and stop.
+* It checks to see if the course will be live before adding it to the requirements tree. If ``--live`` isn't specified, it will ignore your request. This only applies to course creation.
+* If creating a course or program, ``--depts`` must be specified and the department names must exist.
+
+Both of these checks can be overridden with the ``--force`` flag.
+
+Options
+-------
+
+* ``object`` - One of ``program``, ``course``, or ``courserun``
+* ``readable id`` - The readable ID of the object. Note: do not specify the run tag for course runs.
+* ``title`` - The title of the object.
+* ``--live`` - Makes the object live (default is not).
+* ``--force|-f`` - Force the creation of the object. (See "Checks" section for details.)
+* ``--create-depts`` - If specified, any departments specified that do not currently exist will be created.
+
+Programs can take the following options:
+* ``--depts`` - The departments to associate the program with.
+
+Courses can take the following options:
+
+* ``--program <PROGRAM>`` - The program to assign the course to.
+* ``--create-run <run tag>`` - Create a course run for this course with the specified run tag.
+* ``--run-url <url>`` - The courseware URL for the course run. (Only if ``--create-run`` is specified.)
+* ``--self-paced`` - The course run is self-paced. (Only if ``--create-run`` is specified.)
+* ``--required`` - The course is a requirement for the program.
+* ``--elective`` - The course is an elective for the program.
+* ``--depts`` - The departments to associate the course with.
+
+Course runs can take the following options:
+
+* ``--program <PROGRAM>`` - The program to assign the course to. **Required.**
+* ``--run-tag <run tag>`` - The run tag to use. **Required.**
+* ``--run-url <url>`` - The courseware URL for the course run.
+* ``--self-paced`` - The course run is self-paced.
+* ``--start <date>`` - The date the course run should start.
+* ``--end <date>`` - The date the course run should end.
+* ``--enrollment-start <date>`` - The date the course run enrollment should start.
+* ``--enrollment-end <date>`` - The date the course run enrollment should end.
+* ``--upgrade <date>`` - The date after which course run enrollments should not be possible.

_sources/commands/create_courseware_page.rst.txt

@@ -0,0 +1,17 @@
+``create_courseware_page``
+==========================
+
+Creates a very basic About page in the CMS for the given courseware object.
+
+The about page will only have the handful of fields that are required to be there, and will be linked to the specified courseware object. If the courseware object is a course, it will also be added to the Featured Products section on the homepage. By default, the CMS page will be saved in a draft state.
+
+Syntax
+------
+
+``create_courseware_page <courseware id> [--live]``
+
+Options
+-------
+
+* ``courseware id`` - The courseware object to make a CMS page for.
+* ``--live`` - Makes the resulting page live.

_sources/commands/create_product.rst.txt

@@ -0,0 +1,19 @@
+``create_product``
+==================
+
+Creates a product for the given courseware ID. (For now, this only works with course runs.)
+
+By default, the product description will be the courseware ID. This is the recommended setting for this to make it easy to determine which products are for what courseware objects.
+
+Syntax
+------
+
+``create_product <courserun> <price> [--description|-d <description>] [--inactive]``
+
+Options
+-------
+
+* ``courserun`` - The course run to use.
+* ``price`` - The price (numbers only) of the product.
+* ``--description <description>`` (or ``-d``) - Optionally specify the product description. (Defaults to the courseware ID.)
+* ``--inactive`` - Makes the product inactive. (Defaults to active.)

_sources/commands/create_user.rst.txt

@@ -0,0 +1,20 @@
+``create_user``
+===============
+
+Creates a learner account in the system. You will be prompted for the account password.
+
+Syntax
+------
+
+``create_user username email firstname lastname displayname countrycode [--enroll <courseid>]``
+
+Options
+-------
+
+* ``username`` - Username for the learner to create.
+* ``email`` - Email address of the learner to create.
+* ``firstname`` - The learner's first name.
+* ``lastname`` - The learner's last name.
+* ``displayname`` - The learner's display name.
+* ``countrycode`` - The country code to use. (Default US)
+* ``--enroll <courseid>`` - Optionally enroll the user in the specified course run. The enrollment will be an audit enrollment.

_sources/commands/generate_discount_code.rst.txt

@@ -0,0 +1,51 @@
+``generate_discount_code``
+==========================
+
+Creates discount code(s).
+
+This can create a single code, a batch of explicitly defined codes, or a batch of automatically generated codes (with an optional prefix).
+
+Syntax
+------
+
+``generate_discount_code <code> [<code>...] --amount <amount> [-activates <date>] [--expires <date>] [--discount-type <discount type>] [--one-time] [--once-per-user] [--count <count>] [--prefix <prefix>]``
+
+Batch Generating Codes
+----------------------
+
+You can create a batch of explicitly named codes by simply passing multiple discount codes to the command. All of the codes will be created (assuming they don't already exist) with the options you've specified.
+
+Alternatively, you can created a number of codes using the ``--count`` and ``-prefix`` option. Using these options will generate the number of codes specified by ``--count`` and will prefix the code with ``-prefix`` if it is specified. The code will be generated using a UUID - if you've supplied a prefix, the code will be in the format ``<prefix><uuid>``. Note that the command won't insert any punctuation between the prefix and the UUID, so you will need to add that yourself if you want, for example, a dash separating the two. UUIDs are 37 characters in length so prefixes need to be a total of 13 characters or less.
+
+Output
+------
+
+Generated codes will be written to a ``generated-codes.csv`` file, with the following information:
+
+* Discount code
+* Code type
+* Amount
+* Expiration date
+
+The file is overwritten if it exists.
+
+Options
+-------
+
+General options:
+
+* ``--amount <amount>`` - The discount's amount. For percent off discounts, this should be on a scale of 0-100. This is required.
+* ``--discount-type <discount type>`` - One of ``percent-off``, ``dollars-off``, or ``fixed-price``; the type of discount code to make. Defaults to ``percent-off``.
+* ``--activates <date>`` - The date the code should become active (in ISO-8601 format).
+* ``--expires <date>`` - The date the code should stop being active (in ISO-8601 format).
+* ``--one-time`` - Set the discount to be redeemable only once.
+* ``--once-per-user`` - Set the discount to be redeemable only once per learner.
+
+For explicitly named codes:
+
+* ``code`` - The code to generate. (You can specify any number of these.) Max length 50 characters.
+
+For automatically generated codes:
+
+* ``--count <count>`` - The number of codes to create.
+* ``--prefix <prefix>`` - The prefix to append to the code. Max length 13 characters.

_sources/commands/import_courserun.rst.txt

@@ -0,0 +1,56 @@
+``import_courserun``
+====================
+
+Creates courserun(s) in the system based on edX course data.
+
+You can specify either a specific courserun to create, or you can specify a run tag (e.g. ``1T2023``) and a program (e.g. ``program-v1:MITx+DEDP``), and the command will create courseruns for the courses that it finds in edX.
+
+You can also optionally have it create a CMS page for the course, if one doesn't already exist.
+
+Furthermore, you can specify a price, and it will create (or update) product(s) for the courserun(s) with the specified price. Created products will use the readable ID for the courserun as the product description and will be made active depending on the courserun. This command will not update existing courseruns; only new ones that it creates will get products.
+
+If the course does not exist, it will be created with the same data as the edX course. Any specified courserun that doesn't exist in edX will be skipped - it won't make empty course runs for you (use Django Admin or ``create_courseware`` if you want to do that, since you'll need to specify a few things that you can't here.) Similarly, any courserun that already exists will be skipped - ``sync_courserun``, which runs on a regular basis, will handle syncing the pertinent data for it.
+
+New courseruns will be created with the following data synced from the edX course_details API call:
+* Start and end dates
+* Enrollment start and end dates
+* Title
+* Pacing (self-paced or instructor-led)
+* Courseware URL (depends on the ``OPENEDX_API_BASE_URL`` configuration setting)
+
+You may want to adjust these after they're created.
+
+Syntax
+------
+
+To create an individual courserun:
+
+``import_courserun [--courserun <courserun>] [--program <program>] [--live] [--create-cms-page] [--price <price>]``
+
+To walk a program:
+
+``import_courserun [--program <program>] [--run-tag <run tag>] [--live] [--create-cms-page] [--price <price>]``
+
+Options
+-------
+
+* ``--courserun <courserun>`` - The courserun to check for. Takes precedence over ``--program``.
+* ``--program <program>``
+   * _If walking a program:_ The program to walk through. Requires ``--run_tag``. Specify either the numeric database ID or the readable ID for the program.
+   * _If creating a single courserun:_ The program the course should belong to, if any.
+* ``--run-tag <run tag>`` - The run tag to use for the new courseruns. Required for ``--program``; don't use otherwise.
+* ``--live`` - Make the course live. (Default is to set the flag to false.)
+* ``--create-cms-page`` - Attempt to create a basic CMS page for the course, in a similar fashion to ``create_courseware_page``. If this fails (for instance, if the course already has a CMS page), this step will be skipped.
+* ``--price <price>`` - Create (or update) a product for the courserun with the specified price. If the command creates multiple courseruns, this will create a product for each.
+* ``--dept <department_name>`` - Specify department(s) assigned to the course object.  If program is specified, all courses associated with the program and imported will have the same department.
+
+Example
+-------
+
+The use case for this was creating a batch of course runs for an upcoming semester of DEDP courses; these courses existed in edX but not in MITx Online. Since in that case the semester was 1T2023, this command would have created all the applicable courseruns all at once:
+
+``manage.py import_courserun --program program-v1:MITx+DEDP --run-tag 1T2023 --live --dept Economics``
+
+Or, the same but with the standard DEDP pricing applied:
+
+``manage.py import_courserun --program program-v1:MITx+DEDP --run-tag 1T2023 --live --price 1000``

_sources/commands/index.rst.txt

@@ -0,0 +1,22 @@
+MITx Online Commands
+====================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   check_program_requirements
+   configure_instance
+   configure_tiers
+   create_courseware
+   create_courseware_page
+   create_product
+   create_user
+   generate_discount_code
+   import_courserun
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`