docs: reorganize sphinx docs for better discoverability

Author: brian-smith-tcril

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>`.

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.

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.

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]'])"

docs/deployment.rst

@@ -0,0 +1,10 @@
+.. _deployment:
+
+Deploying Tutor
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   local
+   k8s

docs/plugins/v0/api.rst renamed to docs/developing/legacy/api.rst

@@ -1,6 +1,6 @@
-=============
-Legacy v0 API
-=============
+=====================
+Plugins Legacy v0 API
+=====================
 
 .. include:: legacy.rst