docs: reorganize sphinx docs for better discoverability

overhangio · May 23, 2023 · 26216b1 · 26216b1
1 parent 2e276cb
commit 26216b1
Show file tree

Hide file tree

Showing 59 changed files with 591 additions and 642 deletions.
diff --git a/docs/analytics.rst b/docs/analytics.rst
@@ -0,0 +1,7 @@
+Analytics
+=========
+
+Gathering insights and analytics about Open edX
+-----------------------------------------------
+
+Check out `Cairn <https://overhang.io/tutor/plugin/cairn>`__, the next-generation analytics solution for Open edX.
diff --git a/docs/cli.rst b/docs/cli.rst
@@ -0,0 +1,30 @@
+Command line interface (CLI)
+============================
+
+How do I navigate Tutor's command-line interface?
+-------------------------------------------------
+
+Tutor commands are structured in an easy-to-follow hierarchy. At the top level, there are command trees for image and configuration management::
+
+    tutor config ...
+    tutor images ...
+
+as well as command trees for each mode in which Tutor can run::
+
+    tutor local ...  # Commands for managing a local Open edX deployment.
+    tutor k8s ...    # Commands for managing a Kubernetes Open edX deployment.
+    tutor dev ...    # Commands for hacking on Open edX in development mode.
+
+Within each mode, Tutor has subcommands for managing that type of Open edX instance. Many of them are common between modes, such as ``launch``, ``start``, ``stop``, ``exec``, and ``logs``. For example::
+
+    tutor local logs  # View logs of a local deployment.
+    tutor k8s logs    # View logs of a Kubernetes-managed deployment.
+    tutor dev logs    # View logs of a development platform.
+
+Many commands can be further parameterized to specify their target and options, for example::
+
+  tutor local logs cms          # View logs of the CMS container in a local deployment.
+  tutor k8s logs mysql          # View logs of MySQL in Kubernetes-managed deployment.
+  tutor dev logs lms --tail 10  # View ten lines of logs of the LMS container in development mode.
+
+And that's it! You do not need to understand Tutor's entire command-line interface to get started. Using the ``--help`` option that's availble on every command, it is easy to learn as you go. For an in-depth guide, you can also explore the :ref:`CLI Reference <cli_reference>`.
diff --git a/docs/concepts/openedx.rst b/docs/concepts/openedx.rst
@@ -0,0 +1,21 @@
+.. _openedx:
+
+Open edX
+========
+
+What is Open edX?
+-----------------
+
+`Open edX <http://open.edx.org/>`_ is a thriving open source project, backed by a great community, for running an online learning platform at scale. Open edX comes with an LMS (Learning Management System) where students access course contents, a CMS (Content Management System) that course staff uses to design courses, and a few other components to provide more services to students, course staff, and platform administrators.
+
+Should I use Open edX?
+----------------------
+
+Open edX competitors include `Moodle <https://moodle.org/>`__, `Instructure's Canvas <https://www.instructure.com/>`__, `Blackboard's Open LMS <https://www.blackboard.com>`__, as well as a slew of hosted, closed source alternatives. Open edX is the only online learning system that satisfies all following properties:
+
+* Open source software to avoid vendor lock-in
+* Scales well in all directions (number of users and courses)
+* Multiple extension points for comprehensive customization
+* Modern, intuitive user interface to keep students engaged
+
+Open edX is a safe bet: it is backed by edX.org, a US-based non-profit that is committed to open source and which runs Open edX to service its millions of learners. With Open edX you can be sure that the features you need will be available. If it's good enough for Harvard, the MIT, or the French government, then it will probably also work for you.
diff --git a/docs/concepts/tutor.rst b/docs/concepts/tutor.rst
@@ -0,0 +1,16 @@
+.. _tutor_concepts:
+
+Tutor
+=====
+
+What is Tutor?
+--------------
+
+Tutor is an open source distribution of `Open edX <https://open.edx.org>`_. It uses the original code from the various Open edX repositories, such as `edx-platform <https://github.com/openedx/edx-platform/>`_, `cs_comments_service <https://github.com/openedx/cs_comments_service>`_, etc. and packages everything in a way that makes it very easy to install, administer and upgrade Open edX. In particular, all services are run inside Docker containers.
+
+Tutor makes it possible to deploy Open edX locally, with `docker-compose <https://docs.docker.com/compose/overview/>`_ or on an existing `Kubernetes cluster <http://kubernetes.io/>`_.
+
+What is the purpose of Tutor?
+-----------------------------
+
+To make it possible to deploy, administer and upgrade Open edX anywhere, easily.
diff --git a/docs/configuration.rst b/docs/configuration.rst
@@ -6,9 +6,9 @@ Configuration and customisation
 Tutor offers plenty of possibilities for platform customisation out of the box. There are two main ways in which the base Open edX installation can be customised:
 
 a. Modifying the Tutor :ref:`configuration parameters <configuration>`.
-b. Modifying the :ref:`Open edX docker image <customise>` that runs the Open edX platform.
+b. Modifying the :ref:`Open edX docker image <custom_openedx_docker_image>` that runs the Open edX platform.
 
-This section does not cover :ref:`plugin development <plugins>`. For simple changes, such as modifying the ``*.env.yml`` files or the edx-platform settings, *you should not fork edx-platform or tutor*! Instead, you should create a simple :ref:`plugin for Tutor <plugins_yaml>`.
+This section does not cover :ref:`plugin development <plugin_development>`. For simple changes, such as modifying the ``*.env.yml`` files or the edx-platform settings, *you should not fork edx-platform or tutor*! Instead, you should create a simple :ref:`plugin for Tutor <plugin_development_tutorial>`.
 
 .. _configuration:
 
@@ -293,8 +293,6 @@ If you would like to perform SSL/TLS termination with your own custom certificat
 
 .. _customise:
 
-.. _custom_openedx_docker_image:
-
 Kubernetes
 ~~~~~~~~~~
 
@@ -313,6 +311,8 @@ This configuration parameter sets the Contact Email.
 
 This configuration parameter sets the Platform Name.
 
+.. _custom_openedx_docker_image:
+
 Custom Open edX docker image
 ----------------------------
 
@@ -497,3 +497,83 @@ In these situations, you can set ``--docker-arg`` flag in the ``tutor images bui
         --docker-arg="docker.io/myusername/openedx:mytag"
 
 This will result in passing the ``--cache-from`` option with the value ``docker.io/myusername/openedx:mytag`` to the docker build command.
+
+
+Modifying ``edx-platform`` settings
+-----------------------------------
+
+The default settings module loaded by ``edx-platform`` is ``tutor.production`` in production and ``tutor.development`` in development. The folders ``$(tutor config printroot)/env/apps/openedx/settings/lms`` and ``$(tutor config printroot)/env/apps/openedx/settings/cms`` are mounted as ``edx-platform/lms/envs/tutor`` and ``edx-platform/cms/envs/tutor`` inside the docker containers. To modify these settings you must create a plugin that implements one or more of the patch statements in those setting files. See the :ref:`plugin_development_tutorial` tutorial for more information on how to create a plugin.
+
+
+.. _theming:
+
+Installing a custom theme
+-------------------------
+
+Comprehensive theming is enabled by default, but only the default theme is compiled. `Indigo <https://github.com/overhangio/indigo>`__ is a better, ready-to-run theme that you can start using today.
+
+To compile your own theme, add it to the ``env/build/openedx/themes/`` folder::
+
+    git clone https://github.com/me/myopenedxtheme.git \
+      "$(tutor config printroot)/env/build/openedx/themes/myopenedxtheme"
+
+The ``themes`` folder should have the following structure::
+
+    openedx/themes/
+        mycustomtheme1/
+            cms/
+                ...
+            lms/
+                ...
+        mycustomtheme2/
+            ...
+
+Then you must rebuild the openedx Docker image::
+
+    tutor images build openedx
+
+Finally, you should enable your theme with the :ref:`settheme command <settheme>`.
+
+
+Using Google Mail as an SMTP server
+-----------------------------------
+
+By default, Tutor comes with a simple SMTP server for sending emails. Such a server has an important limitation: it does not implement mailing good practices, such as DKIM or SPF. As a consequence. the emails you send might be flagged as spam by their recipients. Thus, you might want to disable the SMTP server and run your own, for instance using your Google Mail account.
+
+.. warning::
+  Google Mail SMTP servers come with their own set of limitations. For instance, you are limited to sending 500 emails a day. Reference: https://support.google.com/mail/answer/22839
+
+You should authorize third-party to access your Google Mail account. In your Google Mail account, select "Manage Account", "Security", and turn on "Less Secure App Access". Check the Google documentation for more information on "less secure apps": https://support.google.com/accounts/answer/6010255
+
+Then, check that you can reach the Google Mail SMTP service from your own server::
+
+    $ telnet smtp.gmail.com 587
+
+If you get ``Connected to smtp.gmail.com.`` then it means that you can successfully reach the Google Mail SMTP servers. If not, you will have to reconfigure your firewall.
+
+To exit the ``telnet`` shell, type ``ctrl+]``, then ``ctrl+d``.
+
+Then, disable the SMTP server that comes with Tutor::
+
+    $ tutor config save --set RUN_SMTP=false
+
+Configure credentials to access your SMTP server::
+
+    $ tutor config save \
+      --set SMTP_HOST=smtp.gmail.com \
+      --set SMTP_PORT=587 \
+      --set SMTP_USE_SSL=false  \
+      --set SMTP_USE_TLS=true \
+      --set [email protected] \
+      --set SMTP_PASSWORD='YOURPASSWORD'
+
+Don't forget to replace your email address and password in the prompt above. If your email password contains special characters, you might have to escape them.
+
+Then, restart your platform::
+
+    $ tutor local launch
+
+That's it! You can send a test email with the following command::
+
+    $ tutor local run --no-deps lms ./manage.py lms shell -c \
+      "from django.core.mail import send_mail; send_mail('test subject', 'test message', '[email protected]', ['[email protected]'])"
diff --git a/docs/deployment.rst b/docs/deployment.rst
@@ -0,0 +1,10 @@
+.. _deployment:
+
+Deploying Tutor
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   local
+   k8s
diff --git a/docs/plugins/v0/api.rst → docs/developing/legacy/api.rst b/docs/plugins/v0/api.rst → docs/developing/legacy/api.rst
diff --git a/docs/plugins/v0/gettingstarted.rst → docs/developing/legacy/gettingstarted.rst b/docs/plugins/v0/gettingstarted.rst → docs/developing/legacy/gettingstarted.rst
diff --git a/docs/plugins/v0/index.rst → docs/developing/legacy/index.rst b/docs/plugins/v0/index.rst → docs/developing/legacy/index.rst
@@ -1,6 +1,6 @@
-=============
-Legacy v0 API
-=============
+=====================
+Plugins Legacy v0 API
+=====================
 
 .. include:: legacy.rst
 

diff --git a/docs/plugins/v0/legacy.rst → docs/developing/legacy/legacy.rst b/docs/plugins/v0/legacy.rst → docs/developing/legacy/legacy.rst
diff --git a/docs/tutorials/nightly.rst → docs/developing/nightly.rst b/docs/tutorials/nightly.rst → docs/developing/nightly.rst
diff --git a/docs/dev.rst → docs/developing/openedx.rst b/docs/dev.rst → docs/developing/openedx.rst
@@ -1,4 +1,4 @@
-.. _development:
+.. _openedx_development:
 
 Open edX development
 ====================
@@ -226,11 +226,9 @@ This override file will be loaded when running any ``tutor dev ..`` command. The
 .. note::
     The ``tutor local`` commands load the ``docker-compose.override.yml`` file from the ``$(tutor config printroot)/env/local/docker-compose.override.yml`` directory. One-time jobs from initialisation commands load the ``local/docker-compose.jobs.override.yml`` and ``dev/docker-compose.jobs.override.yml``.
 
-Common tasks
-------------
 
 XBlock and edx-platform plugin development
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------
 
 In some cases, you will have to develop features for packages that are pip-installed next to the edx-platform. This is quite easy with Tutor. Just add your packages to the ``$(tutor config printroot)/env/build/openedx/requirements/private.txt`` file. To avoid re-building the openedx Docker image at every change, you should add your package in editable mode. For instance::
 
@@ -251,7 +249,7 @@ You will have to re-build the openedx Docker image once::
 You should then run the development server as usual, with ``start``. Every change made to the ``mypackage`` folder will be picked up and the development server will be automatically reloaded.
 
 Running edx-platform unit tests
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 It's possible to run the full set of unit tests that ship with `edx-platform <https://github.com/openedx/edx-platform/>`__. To do so, run a shell in the LMS development container::
 

diff --git a/docs/tutorials/plugin.rst → docs/developing/plugins/creating.rst b/docs/tutorials/plugin.rst → docs/developing/plugins/creating.rst
@@ -47,7 +47,7 @@ Modifying existing files with patches
 
 We'll start by modifying some of our Open edX settings files. It's a frequent requirement to modify the ``FEATURES`` setting from the LMS or the CMS in edx-platform. In the legacy native installation, this was done by modifying the ``lms.env.yml`` and ``cms.env.yml`` files. Here we'll modify the Python setting files that define the edx-platform configuration. To achieve that we'll make use of two concepts from the Tutor API: :ref:`patches` and :ref:`filters`.
 
-If you have not already read :ref:`how_does_tutor_work` now would be a good time ☺️ Tutor uses templates to generate various files, such as settings, Dockerfiles, etc. These templates include ``{{ patch("patch-name") }}`` statements that allow plugins to insert arbitrary content in there. These patches are located at strategic locations. See :ref:`patches` for more information.
+If you have not already read :ref:`how_tutor_works` now would be a good time ☺️ Tutor uses templates to generate various files, such as settings, Dockerfiles, etc. These templates include ``{{ patch("patch-name") }}`` statements that allow plugins to insert arbitrary content in there. These patches are located at strategic locations. See :ref:`patches` for more information.
 
 Let's say that we would like to limit access to our brand new Open edX platform. It is not ready for prime-time yet, so we want to prevent users from registering new accounts. There is a feature flag for that in the LMS: `FEATURES['ALLOW_PUBLIC_ACCOUNT_CREATION'] <https://edx.readthedocs.io/projects/edx-platform-technical/en/latest/featuretoggles.html#featuretoggle-FEATURES['ALLOW_PUBLIC_ACCOUNT_CREATION']>`__. By default this flag is set to a true value, enabling anyone to create an account. In the following we'll set it to false.
 

diff --git a/docs/plugins/examples.rst → docs/developing/plugins/examples.rst b/docs/plugins/examples.rst → docs/developing/plugins/examples.rst
diff --git a/docs/developing/plugins/index.rst b/docs/developing/plugins/index.rst
@@ -0,0 +1,12 @@
+.. _plugin_development:
+
+========================
+Tutor plugin development
+========================
+
+.. toctree::
+   :maxdepth: 2
+
+   creating
+   examples
+   indexes
diff --git a/docs/reference/indexes.rst → docs/developing/plugins/indexes.rst b/docs/reference/indexes.rst → docs/developing/plugins/indexes.rst
diff --git a/docs/tutorials/theming.rst → docs/developing/themes.rst b/docs/tutorials/theming.rst → docs/developing/themes.rst
@@ -1,39 +1,7 @@
-.. _theming:
-
-Changing the appearance of Open edX
-===================================
-
-Installing a custom theme
--------------------------
-
-Comprehensive theming is enabled by default, but only the default theme is compiled. `Indigo <https://github.com/overhangio/indigo>`__ is a better, ready-to-run theme that you can start using today.
-
-To compile your own theme, add it to the ``env/build/openedx/themes/`` folder::
-
-    git clone https://github.com/me/myopenedxtheme.git \
-      "$(tutor config printroot)/env/build/openedx/themes/myopenedxtheme"
-
-The ``themes`` folder should have the following structure::
-
-    openedx/themes/
-        mycustomtheme1/
-            cms/
-                ...
-            lms/
-                ...
-        mycustomtheme2/
-            ...
-
-Then you must rebuild the openedx Docker image::
-
-    tutor images build openedx
-
-Finally, you should enable your theme with the :ref:`settheme command <settheme>`.
-
 .. _theme_development:
 
-Developing a new theme
-----------------------
+Open edX theme development 
+--------------------------
 
 With Tutor, it's pretty easy to develop your own themes. Start by placing your files inside the ``env/build/openedx/themes`` directory. For instance, you could start from the ``edx.org`` theme present inside the ``edx-platform`` repository::
 
@@ -54,4 +22,4 @@ Watch the themes folders for changes (in a different terminal)::
 
     tutor dev run watchthemes
 
-Make changes to some of the files inside the theme directory: the theme assets should be automatically recompiled and visible at http://local.overhang.io:8000.
+Make changes to some of the files inside the theme directory: the theme assets should be automatically recompiled and visible at http://local.overhang.io:8000.