docs: Fix links broken due to refactor in previous commit

This changes a number of links to `:doc:` or `:ref:` links, and removes the
readme.rst inclusion (now that the README is very small). It also adds the
new pages to the table of contents, and moves Workflow to a higher
position.

Author: timmc-edx

README.rst

@@ -16,7 +16,7 @@ Where to Find Help
 
 There are a number of places to get help, including mailing lists and real-time chat. Please choose an appropriate venue for your question. This helps ensure that you get good prompt advice, and keeps discussion focused. For details of your options, see the `Community`_ pages.
 
-- See the `most common development workflow`_ (after you've finished `Getting Started`_).
+- See the `most common development workflow`_ (after you've finished :doc:`getting_started`).
 - See the `Devstack Interface`_
 - See some `helpful troubleshooting tips`_.
 - See the `Frequently Asked Questions`_.
@@ -38,13 +38,8 @@ You can also browse all the documentation in `Read the Docs`_.
 Notices
 -------
 
-**NOTE:** LMS is now using MySql 5.7 by default. You have to run ``make dev.pull.lms`` and ``make dev.provision.lms`` (more details in `Getting Started`_) to fetch latest images and reprovision local copies of databases in order for an existing devstack setup to keep working.
+**NOTE:** LMS is now using MySql 5.7 by default. You have to run ``make dev.pull.lms`` and ``make dev.provision.lms`` (more details in :doc:`getting_started`) to fetch latest images and reprovision local copies of databases in order for an existing devstack setup to keep working.
 
-.. _Docker Compose: https://docs.docker.com/compose/
-.. _Docker for Mac: https://docs.docker.com/docker-for-mac/
-.. _licensing terms: https://www.docker.com/pricing/faq
-.. _Docker for Windows: https://docs.docker.com/docker-for-windows/
-.. _configuring Docker for Mac: https://docs.docker.com/docker-for-mac/#/advanced
 .. _feature added in Docker 17.05: https://github.com/openedx/configuration/pull/3864
 .. _edx-e2e-tests README: https://github.com/edx/edx-e2e-tests/#how-to-run-lms-and-studio-tests
 .. _edxops Docker image: https://hub.docker.com/r/edxops/
@@ -61,5 +56,4 @@ Notices
     :alt: Documentation Status
     :scale: 100%
     :target: https://edx.readthedocs.io/projects/open-edx-devstack/en/latest/
-.. _Python virtualenv: https://docs.python-guide.org/en/latest/dev/virtualenvs/#lower-level-virtualenv
 .. _Community: https://open.edx.org/community/connect/

docs/developing_on_named_release_branches.rst

@@ -3,32 +3,29 @@ Developing on Open edX named release branches
 
 .. contents:: Table of Contents
 
-By default, the startup steps in `README.rst`_ will install the devstack using the master branch of all repos. If you want to install a named release instead, follow these steps before pulling the docker images in step 3 of the `Getting Started`_ guide:
+By default, the startup steps in :doc:`getting_started` will install the devstack using the master branch of all repos. If you want to install a named release instead, follow these steps before the step that pulls the docker images:
 
 #. Set the ``OPENEDX_RELEASE`` environment variable to the appropriate image
    tag; "hawthorn.master", "zebrawood.rc1", etc.  Note that unlike a server
    install, ``OPENEDX_RELEASE`` should not have the "open-release/" prefix.
 #. Check out the appropriate branch in devstack, e.g. ``git checkout open-release/ironwood.master``
 #. Use ``make dev.checkout`` to check out the correct branch in the local
    checkout of each service repository
-#. Continue with step 3 in the `getting started`_ guide to pull the correct docker images.
+#. Continue with step 3 in :doc:`getting_started` to pull the correct docker images.
 
 All ``make`` target and ``docker-compose`` calls should now use the correct
 images until you change or unset ``OPENEDX_RELEASE`` again.  To work on the
 master branches and ``latest`` images, unset ``OPENEDX_RELEASE`` or set it to
 an empty string.
 
-.. _README.rst: https://github.com/openedx/devstack
-.. _getting started: https://github.com/openedx/devstack#getting-started
-
 How do I run multiple named Open edX releases on same machine?
 --------------------------------------------------------------
 You can have multiple isolated Devstacks provisioned on a single computer now. Follow these directions **after installing at least two devstacks** to switch between them.
 
-#. If you haven't done so, follow the steps in the `Getting Started`_ section, to install the master devstack or any other named release. We recommend that you have at least one devstack on the master branch.
+#. If you haven't done so, follow the steps in :doc:`getting_started`, to install the master devstack or any other named release. We recommend that you have at least one devstack on the master branch.
 #. Change directory to your devstack and activate the virtual env.
 #. Stop any running containers by issuing a ``make dev.stop``.
-#. Follow the steps in `Getting Started`_ section again, setting the additional OPENEDX_RELEASE you want to install in step 2
+#. Follow the steps in :doc:`getting_started` again, setting the additional OPENEDX_RELEASE you want to install in step 2
 
 The implication of this is that you can switch between isolated Devstack databases by changing the value of the ``OPENEDX_RELEASE`` environment variable.
 

docs/getting_started.rst

@@ -38,6 +38,11 @@ If you are using Linux, use the ``overlay2`` storage driver, kernel version
 
    docker info | grep -i 'storage driver'
 
+.. _Docker for Mac: https://docs.docker.com/docker-for-mac/
+.. _licensing terms: https://www.docker.com/pricing/faq
+.. _configuring Docker for Mac: https://docs.docker.com/docker-for-mac/#/advanced
+.. _Docker for Windows: https://docs.docker.com/docker-for-windows/
+
 Please note
 ~~~~~~~~~~~
 
@@ -46,15 +51,15 @@ from within a Virtual Machine, as these commands are meant to stand up a VM-like
 Docker containers.
 
 However, you may want to run the ``make`` commands from within a Python 3 virtual
-environment, as described in `Getting Started`_. This will keep the Python packages required for Devstack separate from
+environment. This will keep the Python packages required for Devstack separate from
 the ones installed globally on your system.
 
 Directions to setup devstack
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The default devstack services can be run by following the steps below.
 
-**Note:** This will set up a large number of services, more than you are likely to need to work with, but that's only necessary for first-time provisioning. See `Service List`_ and the `most common development workflow`_ for how to run and update devstack with just the services you need, rather than the ``large-and-slow`` default set.
+**Note:** This will set up a large number of services, more than you are likely to need to work with, but that's only necessary for first-time provisioning. See :doc:`service_list` and the :doc:`most common development workflow <workflow>` for how to run and update devstack with just the services you need, rather than the ``large-and-slow`` default set.
 
 #. Install the requirements inside of a `Python virtualenv`_.
 
@@ -164,4 +169,6 @@ This data collection is behind a consent flag, so please help devstack's maintai
 
    make metrics-opt-in
 
-Now that you're up and running, read about the `most common development workflow`_.
+Now that you're up and running, read about the :doc:`most common development workflow <workflow>`.
+
+.. _Python virtualenv: https://docs.python-guide.org/en/latest/dev/virtualenvs/#lower-level-virtualenv

docs/index.rst

@@ -1,5 +1,5 @@
 Open edX Devstack
-=================
+#################
 
 Devstack is the local Docker-based environment for developing in the Open edX platform.
 
@@ -29,25 +29,31 @@ It also includes the following extra components:
 * The course-authoring micro-frontend
 * The enhanced staff grader (ora-grading) micro-frontend
 
-Contents:
+  .. _Docker Compose: https://docs.docker.com/compose/
+
+Contents
+********
 
 .. toctree::
    :maxdepth: 2
 
-   readme
+   getting_started
+   logging_in
+   workflow
+   service_list
    devstack_interface
    devstack_faq
-   workflow
    building-images
    database-dumps
    devpi
    developing_on_named_release_branches
    pycharm_integration
    testing_and_debugging
    troubleshoot_general_tips
+   advanced_configuration
 
 Indices and tables
-==================
+******************
 
 * :ref:`genindex`
 * :ref:`modindex`

docs/pycharm_integration.rst

@@ -10,7 +10,7 @@ Prerequisites
 -------------
 
 1. You must complete all steps for provisioning your Docker Devstack environment
-   in the `README`_ before proceeding with the PyCharm setup.
+   in :doc:`getting_started` before proceeding with the PyCharm setup.
 
 2. If you are on a Mac, make sure you are on a newer version than macOS
    Yosemite. A this time, this should work with either El Capitan or Sierra.
@@ -343,5 +343,4 @@ One way to do this is to follow these instructions:
 .. _Jetbrains ticket PY-22893: https://youtrack.jetbrains.com/issue/PY-22893
 .. _PyCharm: https://www.jetbrains.com/pycharm/
 .. _PyCharm IDE setup: https://openedx.atlassian.net/wiki/spaces/AC/pages/92209229/PyCharm
-.. _README: ../README.rst
 .. _vendor documentation: https://www.jetbrains.com/help/pycharm/2017.1/configuring-remote-interpreters-via-docker-compose.html

docs/readme.rst

@@ -8,7 +8,7 @@ as well as links to the repository where each service's code lives.
 
 Most developers will be best served by working with specific combinations of these services, for example ``make dev.pull.studio`` or ``make dev.up.ecommerce``. These will pull in dependencies as needed—starting ecommerce will also start lms, and lms will pull in forums, discovery, and others. If you need multiple, they can be listed like ``make dev.up.studio+ecommerce``. After the service table below there is a list of some common combinations.
 
-Instead of a service name or list, you can also run commands like ``make dev.provision`` / ``make dev.pull.large-and-slow`` / ``make dev.up.large-and-slow``. This is a larger list than most people will need for most of their work, and includes all of the services marked "Default" in the below table. (Some of these targets use ``large-and-slow`` in their name as a warning; others may be changed to use this over time.) However, you can change this list by modifying the ``DEFAULT_SERVICES`` option as described in the `Advanced Configuration Options`_ section.
+Instead of a service name or list, you can also run commands like ``make dev.provision`` / ``make dev.pull.large-and-slow`` / ``make dev.up.large-and-slow``. This is a larger list than most people will need for most of their work, and includes all of the services marked "Default" in the below table. (Some of these targets use ``large-and-slow`` in their name as a warning; others may be changed to use this over time.) However, you can change this list by modifying the ``DEFAULT_SERVICES`` option as described in :doc:`advanced_configuration`.
 
 +------------------------------------+-------------------------------------+----------------+--------------+
 | Service                            | URL                                 | Type           | Role         |

docs/service_list.rst

@@ -58,7 +58,7 @@ You can routinely create backups of your local databases. To create a backup, us
 Running micro-frontends outside of devstack
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Although several micro-frontends (MFEs) are built into devstack (the full list is in the `service table`_), some users prefer to run those MFEs directly on their host machine. You can achieve this by first removing the devstack MFE container, and then starting the host version. For example::
+Although several micro-frontends (MFEs) are built into devstack (the full list is in :doc:`service_list`), some users prefer to run those MFEs directly on their host machine. You can achieve this by first removing the devstack MFE container, and then starting the host version. For example::
 
   make dev.down.frontend-app-learning  # Bring down the devstack version of the Learning MFE.
   cd <path-to-frontend-app-learning>   # Navigate to the Learning MFE's repository.
@@ -67,5 +67,3 @@ Although several micro-frontends (MFEs) are built into devstack (the full list i
 Of course ``learning`` can be replaced with ``gradebook``, ``payment``, or another frontend-app name.
 
 If you forget to bring down the devstack version of the MFE, you will notice a port conflict when trying to start the host version.
-
-.. _service table: ../README.rst#service-list