docs: advertise Cairn and the maintainers group

Here we add to the docs a few shameless plugs about Cairn -- because
it's really awesome!
We also add a few improvements to the wording, here and there.

README.rst

@@ -32,7 +32,15 @@ Tutor: the docker-based Open edX distribution designed for peace of mind
     :alt: AGPL License
     :target: https://www.gnu.org/licenses/agpl-3.0.en.html
 
-**Tutor** is a docker-based `Open edX <https://openedx.org>`_ distribution, both for production and local development. The goal of Tutor is to make it easy to deploy, customize, upgrade and scale Open edX. Tutor is reliable, fast, extensible, and it is already used by hundreds of Open edX platforms around the world.
+.. image:: https://img.shields.io/twitter/follow/overhangio
+    :alt: Follow us on Twitter
+    :target: https://twitter.com/overhangio/
+
+.. image:: https://img.shields.io/youtube/channel/views/UCe_p_Axq3PjRnbTqFZDY_iQ?label=Overhang.IO%20on%20Youtube
+    :alt: Follow us on Youtube
+    :target: https://www.youtube.com/c/OverhangIO
+
+**Tutor** is the Docker-based `Open edX <https://openedx.org>`_ distribution, both for production and local development. The goal of Tutor is to make it easy to deploy, customize, upgrade and scale Open edX. Tutor is reliable, fast, extensible, and it is already used by hundreds of Open edX platforms around the world.
 
 Do you need professional assistance setting up or managing your Open edX platform? Overhang.IO provides online support as part of its `Long Term Support (LTS) offering <https://overhang.io/tutor/pricing>`__.
 
@@ -45,8 +53,8 @@ Features
 * Comes with batteries included: `theming <https://github.com/overhangio/indigo>`__, `SCORM <https://github.com/overhangio/openedx-scorm-xblock>`__, `HTTPS <https://docs.tutor.overhang.io/configuration.html#ssl-tls-certificates-for-https-access>`__, `web-based administration interface <https://github.com/overhangio/tutor-webui>`__, `mobile app <https://github.com/tutor/tutor-android>`__, `custom translations <https://docs.tutor.overhang.io/configuration.html#adding-custom-translations>`__...
 * Extensible architecture with `plugins <https://docs.tutor.overhang.io/plugins.html>`__
 * Works with `Kubernetes <https://docs.tutor.overhang.io/k8s.html>`__
+* Amazing premium plugins available in the `Tutor Wizard Edition <https://overhang.io/tutor/wizardedition>`__, including `Cairn <https://overhang.io/tutor/plugin/cairn>`__ the next-generation analytics solution for Open edX.
 * No technical skill required with the `1-click Tutor AWS image <https://docs.tutor.overhang.io/install.html#cloud-deployment>`__
-* Amazing premium plugins available in the `Tutor Wizard Edition <https://overhang.io/tutor/wizardedition>`__
 
 .. _readme_intro_end:
 

docs/faq.rst

@@ -8,7 +8,7 @@ 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/edx/edx-platform/>`_, `cs_comments_service <https://github.com/edx/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/>`_.
+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/>`_. Want to learn more? Take a look at the :ref:`getting started concepts <intro>`.
 
 What is the purpose of Tutor?
 -----------------------------
@@ -38,26 +38,21 @@ The `devstack <https://github.com/edx/devstack>`_ is meant for development only,
 Is Tutor officially supported by edX?
 -------------------------------------
 
-No. Tutor is developed independently from edX. That means that the folks at edX.org are *not* responsible for troubleshooting issues of this project. Please don't bother Ned ;-)
+As of the Open edX Lilac release (June 9th 2021), Tutor is one of the two officially supported installation methods for Open edX: see the `official installation instructions <https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/open-release-lilac.master/installation/index.html>`__. We expect that by Maple (December 9th 2021) the native installation will be deprecated and Tutor will become the only officially recommended installation method, unless major issues are discovered. However, Tutor remains developed independently from edX, both by its parent company Overhang.IO and the :ref:`project maintainers <maintainers>`.
 
 What features are missing from Tutor?
 -------------------------------------
 
-Tutor tries very hard to support all major Open edX features, notably in the form of :ref:`plugins <existing_plugins>`. In particular, the discovery and ecommerce services, once unavailable in Tutor, can now be easily installed via plugins. If you are interested in sponsoring the development of a new plugin, please `get in touch <mailto:[email protected]>`__!
+Tutor tries very hard to support all major Open edX features, notably in the form of :ref:`plugins <existing_plugins>`. If you are interested in sponsoring the development of a new plugin, please `get in touch <mailto:[email protected]>`__!
 
-It should be noted that the `Analytics <https://github.com/edx/edx-analytics-pipeline>`__ stack is currently unsupported, and will likely stay so in the future, as it would require a tremendous amount of work to containerize all the components. We are currently working on a replacement solution.
+It should be noted that the `Insights <https://github.com/edx/edx-analytics-pipeline>`__ stack is currently unsupported, because of its complexity, lack of support and extensibility. To replace it, Overhang.IO developed `Cairn <https://overhang.io/tutor/plugin/cairn>`__ the next-generation analytics solution for Open edX, part of the `Tutor Wizard Edition <https://overhang.io/tutor/wizardedition>`__. You should check it out 😉
 
 Are there people already running this in production?
 ----------------------------------------------------
 
-Yes, many of them. There is no way to count precisely how many running Open edX platforms were deployed with Tutor, but from feedback collected directly from real users, there must be hundreds, if not thousands. Tutor is also used by some Open edX providers who are hosting platforms for their customers.
+Yes: system administrators all around the world use Tutor to run their Open edX platforms, from single-class school teachers to renowned universities, Open edX SaaS providers and nation-wide learning platforms.
 
 Why should I trust software written by some random guy on the Internet?
 -----------------------------------------------------------------------
 
-You shouldn't :) Tutor is actively maintained by `Overhang.IO <https://overhang.io>`_, a France-based company founded by `Régis Behmo <https://github.com/regisb/>`_. Régis has been working on Tutor since early 2018; he has been a contributor of the Open edX project since 2015. In particular, he has worked for 2 years at `FUN-MOOC <https://www.fun-mooc.fr/>`_, one of the top 5 largest Open edX platforms in the world. He presented several talks at the Open edX conferences:
-
-- *Deploying a robust, scalable Open edX platform in 1 click (or less) with Tutor*, March 2019 (`video <https://www.youtube.com/watch?v=Oqc7c-3qFc4>`_, `slides <https://regisb.github.io/openedx2019/>`_)
-- *Videofront: a Self-Hosted YouTube*, June 2017 (`video <https://www.youtube.com/watch?v=e7bJchJrmP8&t=5m53s>`__, `slides <http://regisb.github.io/openedx-conference-2017/>`__)
-- *Open edX 101: A Source Code Review*, June 2016 (`video <https://www.youtube.com/watch?v=DVku7Y7XQII>`__, `slides <http://regisb.github.io/openedx-conference-2016/>`__)
-- *FUN: Life in the Avant-Garde*, Oct. 2015 (`video <https://www.youtube.com/watch?v=V1EBo1l8BgY>`__, `slides <http://regisb.github.io/openedx-conference-2015/>`__)
+You shouldn't :) Tutor is actively maintained by `Overhang.IO <https://overhang.io>`_, a France-based company founded by `Régis Behmo <https://github.com/regisb/>`_. Régis has been working on Tutor since early 2018; he has been a contributor of the Open edX project since 2015. In particular, he has worked for 2 years at `FUN-MOOC <https://www.fun-mooc.fr/>`_, one of the top 5 largest Open edX platforms in the world. In addition, the Tutor project is a community-led project with many contributions from its :ref:`project maintainers <maintainers>`.

docs/gettingstarted.rst

@@ -5,7 +5,7 @@ Getting started
 
 .. toctree::
    :maxdepth: 2
-   
+
    intro
    quickstart
    install

docs/intro.rst

@@ -73,22 +73,33 @@ The platform is reset every day at 9:00 AM, `Paris (France) time <https://time.i
 How does Tutor work?
 --------------------
 
+Tutor is a piece of software that takes care of exactly three things:
+
+1. Project configuration: user-specific settings (such as secrets) are stored in a single ``config.yml`` file.
+2. Template rendering: all the files that are necessary to run your platform are generated from a set of templates and the user-specific settings.
+3. Command-line interface (CLI): frequently-used administration commands are gathered in a convenient, unified CLI.
+
 You can experiment with Tutor very quickly: start by `installing <install>`_ Tutor. Then run::
 
-    tutor config save --interactive
+    $ tutor config save --interactive
+
+Then, to view the result of the above command::
+
+    $ cd "$(tutor config printroot)"
+    $ ls
+    config.yml  env
 
-This command does two things:
+The ``config.yml`` file contains your user-specific Open edX settings (item #1 above). The ``env/`` folder contains the rendered templates which will be used to run your Open edX platform (item #2). For instance, the ``env/local`` folder contains the ``docker-compose.yml`` file to run Open edX locally.
 
-1. Generate a ``config.yml`` configuration file: this file contains core :ref:`configuration parameters <configuration>` for your Open edX platforms, such as passwords and feature flags.
-2. Generate an ``env/`` folder, which we call the Tutor "environment", and which contains all the files that are necessary to run an Open edX platform: these are mostly Open edX configuration files.
+The values from ``config.yml`` are used to generate the environment files in ``env/``. As a consequence, **every time the values from** ``config.yml`` **are modified, the environment must be regenerated** with ``tutor config save``..
 
-All these files are stored in a single folder, called the Tutor project root. On Linux, this folder is in ``~/.local/share/tutor``. On Mac OS it is ``~/Library/Application Support/tutor``.
+Because the Tutor environment is generated entirely from the values in ``config.yml``, you can ``rm -rf`` the ``env/`` folder at any time and re-create it with ``tutor config save``. Another consequence is that **any manual change made to a file in** ``env/`` **will be overwritten by** ``tutor config save`` **commands**. Consider yourself warned!
 
-The values from ``config.yml`` are used to generate the environment files in ``env/``. As a consequence, **every time the values from** ``config.yml`` **are modified, the environment must be regenerated**. This can be done with::
+You can now take advantage of the Tutor-powered CLI (item #3) to bootstrap your Open edX platform::
 
-    tutor config save
+    tutor local quickstart
 
-Another consequence is that **any manual change made to a file in** ``env/`` **will be overwritten by** ``tutor config save`` **commands**. Consider yourself warned!
+Under the hood, Tutor simply runs ``docker-compose`` and ``docker`` commands to launch your platform. These commands are printed in the standard output, such that you are free to replicate the same behaviour by simply copy/pasting the same commands.
 
 I'm ready, where do I start?
 ----------------------------

docs/tutor.rst

@@ -3,20 +3,23 @@
 Tutor development
 =================
 
+Setting up your development environment
+---------------------------------------
+
 Start by cloning the Tutor repository::
 
     git clone https://github.com/overhangio/tutor.git
     cd tutor/
 
 Install requirements
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
 ::
 
     pip install -r requirements/dev.txt
 
 Run tests
----------
+~~~~~~~~~
 
 ::
 
@@ -25,7 +28,7 @@ Run tests
 Yes, there are very few unit tests for now, but this is probably going to change.
 
 Code formatting
----------------
+~~~~~~~~~~~~~~~
 
 Tutor code formatting is enforced by `black <https://black.readthedocs.io/en/stable/>`_. To check whether your code changes conform to formatting standards, run::
 
@@ -39,15 +42,18 @@ Static error detection is performed by `pylint <https://pylint.readthedocs.io/en
 
     make test-lint
 
-Bundle ``tutor`` executable
----------------------------
+Common developer tasks
+----------------------
+
+Generating the ``tutor`` executable binary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
     make bundle
 
 Generating the documentation
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
@@ -60,7 +66,7 @@ You can then browse the documentation with::
     make browse
 
 Releasing a new version
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 - Bump the ``__version__`` value in ``tutor/__about__.py``.
 - Replace "Unreleased" by the version name and date in CHANGELOG.md.
@@ -76,17 +82,20 @@ Third-party contributions to Tutor and its plugins are more than welcome! Just m
 
 - Outside of obvious bugs, contributions should be discussed first in the `official Tutor forums <https://discuss.overhang.io>`__.
 - Once we agree on a high-level solution, you should open a pull request on the `Tutor repository <https://github.com/overhangio/tutor/pulls>`__ or the corresponding plugin.
-- Write a good Git commit title and message: explain why you are making this change, what problem you are solving and which solution you adopted. Link to the relevant conversation topics in the forums and describe your use case. We *love* long, verbose descriptions :)
 - Make sure that all tests pass by running ``make test`` (see above).
 - If your PR is in the Tutor core repository, add an item to the CHANGELOG file, in the "Unreleased" section. Use the same format as the other items::
 
     - [TYPE] DESCRIPTION
 
 Where "TYPE" is either "Bugfix", "Improvement", "Feature" or "Security". You should add an explosion emoji ("💥") before "[TYPE]" if you are making a breaking change.
 
+- Write a good Git commit title and message: explain why you are making this change, what problem you are solving and which solution you adopted. Link to the relevant conversation topics in the forums and describe your use case. We *love* long, verbose descriptions :) As for the title, `conventional commits <https://www.conventionalcommits.org>`__ are preferred. Check the repo history!
+
 Happy hacking! ☘️
 
+.. _maintainers:
+
 Joining the team of Tutor Maintainers
 -------------------------------------
 
-We have an open team of volunteers who help support the project. You can read all about it `here <https://discuss.overhang.io/t/the-tutor-maintainer-handbook/1375>`__.
+We have an open team of volunteers who help support the project. You can read all about it `here <https://discuss.overhang.io/t/the-tutor-maintainer-handbook/1375>`__ -- and we hope that you'll consider joining us 😉

docs/whatnext.rst

@@ -35,6 +35,11 @@ Deploying to Kubernetes
 
 Yes, Tutor comes with Kubernetes deployment support :ref:`out of the box <k8s>`.
 
+Gathering insights and analytics about Open edX
+-----------------------------------------------
+
+Check out `Cairn <https://overhang.io/tutor/plugin/cairn>`__, the next-generation analytics solution for Open edX.
+
 Meeting the community
 ---------------------
 

setup.py

@@ -7,7 +7,9 @@
 
 def load_readme():
     with io.open(os.path.join(HERE, "README.rst"), "rt", encoding="utf8") as f:
-        return f.read()
+        readme = f.read()
+    # Replace img src for publication on pypi
+    return readme.replace("./docs/img/", "https://github.com/overhangio/tutor/raw/master/docs/img/")
 
 
 def load_about():