doc/install: update clone-source.rst

Beef up clone-source.rst. Repair semantics. Add internal references. Fix
a broken "git submodule foreach git clean -fdx" command.

Signed-off-by: Zac Dover <zac.dover@gmail.com>

diff --git a/doc/install/clone-source.rst b/doc/install/clone-source.rst
index 6a55a880e7feb1c4ad3484520b5b8229f1405210..85b11f352ab94f812300ab6ea0504a1bb6e90d1a 100644 (file)
--- a/doc/install/clone-source.rst
+++ b/doc/install/clone-source.rst
@@ -2,33 +2,37 @@
  Cloning the Ceph Source Code Repository
 =========================================
 
-You may clone a Ceph branch of the Ceph source code by going to `github Ceph
-Repository`_,  selecting a branch (``main`` by default), and clicking the
-**Download ZIP** button.
+To clone a Ceph branch of the Ceph source code, go to `github Ceph
+Repository`_, select a branch (``main`` by default), and click the **Download
+ZIP** button.
 
 .. _github Ceph Repository: https://github.com/ceph/ceph
 
+To clone the entire git repository, :ref:`install <install-git>` and configure
+``git``.
 
-To clone the entire git repository, install and configure ``git``.
-
+.. _install-git:
 
 Install Git
 ===========
 
-To install ``git`` on Debian/Ubuntu, execute::
+To install ``git`` on Debian/Ubuntu, run the following command:
+
+.. prompt:: bash $
+
+   sudo apt-get install git
 
-       sudo apt-get install git
 
+To install ``git`` on CentOS/RHEL, run the following command:
 
-To install ``git`` on CentOS/RHEL, execute::
+.. prompt:: bash $
 
-       sudo yum install git
+   sudo yum install git
 
 
-You must also have a ``github`` account. If you do not have a
-``github`` account, go to `github.com`_ and register.
-Follow the directions for setting up git at 
-`Set Up Git`_.
+You must have a ``github`` account. If you do not have a ``github``
+account, go to `github.com`_ and register.  Follow the directions for setting
+up git at `Set Up Git`_.
 
 .. _github.com: https://github.com
 .. _Set Up Git: https://help.github.com/linux-set-up-git
@@ -37,26 +41,31 @@ Follow the directions for setting up git at
 Add SSH Keys (Optional)
 =======================
 
-If you intend to commit code to Ceph or to clone using SSH
+To commit code to Ceph or to clone the respository by using SSH
 (``git@github.com:ceph/ceph.git``), you must generate SSH keys for github. 
 
-.. tip:: If you only intend to clone the repository, you may 
+.. tip:: If you want only to clone the repository, you can 
    use ``git clone --recursive https://github.com/ceph/ceph.git`` 
    without generating SSH keys.
 
-To generate SSH keys for ``github``, execute::
+To generate SSH keys for ``github``, run the following command:
+
+.. prompt:: bash $
+
+   ssh-keygen
 
-       ssh-keygen
+To print the SSH key that you just generated and that you will add to your
+``github`` account, use the ``cat`` command. (The following example assumes you
+used the default file path.):
 
-Get the key to add to your ``github`` account (the following example
-assumes you used the default file path)::
+.. prompt:: bash $
 
-       cat .ssh/id_rsa.pub
+   cat .ssh/id_rsa.pub
 
 Copy the public key.
 
-Go to your ``github`` account, click on "Account Settings" (i.e., the
-'tools' icon); then, click "SSH Keys" on the left side navbar.
+Go to your ``github`` account, click "Account Settings" (represented by the
+'tools' icon), and click "SSH Keys" on the left side navbar.
 
 Click "Add SSH key" in the "SSH Keys" list, enter a name for the key, paste the
 key you generated, and press the "Add key" button.
@@ -65,21 +74,24 @@ key you generated, and press the "Add key" button.
 Clone the Source
 ================
 
-To clone the Ceph source code repository, execute::
+To clone the Ceph source code repository, run the following command:
 
-       git clone --recursive https://github.com/ceph/ceph.git
+.. prompt:: bash $
 
-Once ``git clone`` executes, you should have a full copy of the Ceph 
+   git clone --recursive https://github.com/ceph/ceph.git
+
+After ``git clone`` has run, you should have a full copy of the Ceph 
 repository.
 
-.. tip:: Make sure you maintain the latest copies of the submodules
-   included in the repository. Running ``git status`` will tell you if
-   the submodules are out of date.
+.. tip:: Make sure you maintain the latest copies of the submodules included in
+   the repository. Running ``git status`` will tell you whether the submodules
+   are out of date. See :ref:`update-submodules` for more information.
 
-::
 
-       cd ceph
-       git status
+.. prompt:: bash $
+
+   cd ceph
+   git status
 
 .. _update-submodules:
 
@@ -144,7 +156,11 @@ Updating Submodules
 
       git submodule update --force --init --recursive
       git clean -fdx
-      git submodule foreach clean -fdx
+      git submodule foreach git clean -fdx
+
+   If you still have problems with a submodule directory, use ``rm -rf
+   [directory name]`` to remove the directory. Then run ``git submodule update
+   --init --recursive`` again.
 
 #. Run ``git status`` again: