doc/start: edit documenting-ceph.rst

Edit the section "Build the Source (First Time)" in
doc/start/documenting-ceph.rst.

- remove references to RHEL7 (it's old)
- improve sentences (they were first-draft-like)
- improve RST formatting

Signed-off-by: Zac Dover <zac.dover@proton.me>
(cherry picked from commit 24771aecdcfb43c01bf3b54c87ce329b90d13389)

diff --git a/doc/start/documenting-ceph.rst b/doc/start/documenting-ceph.rst
index 02c6db96555913fee46e8656e24a48853a44499a..82ccb1503bacbc412a95aff9359c89e7f963bea3 100644 (file)
--- a/doc/start/documenting-ceph.rst
+++ b/doc/start/documenting-ceph.rst
@@ -282,14 +282,16 @@ documentation in HTML and manpage formats respectively.
 Build the Source (First Time)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Ceph uses Python Sphinx, which is generally distribution agnostic. The first
-time you build Ceph documentation, it will generate a doxygen XML tree, which
-is a bit time consuming.
+Ceph uses Python Sphinx, which is distribution agnostic. The first time you
+build the Ceph documentation, a doxygen XML tree is generated. This can be time
+-consuming.
 
-Python Sphinx does have some dependencies that vary across distributions. The
-first time you build the documentation, the script will notify you if you do not
-have the dependencies installed. To run Sphinx and build documentation successfully,
-the following packages are required:
+Some of Python Sphinx's dependencies vary across distributions. The first time
+you build the documentation, the build script notifies you of uninstalled
+dependencies. 
+
+To run Sphinx and build documentation successfully, the following packages are
+required:
 
 .. raw:: html
 
@@ -350,14 +352,14 @@ the following packages are required:
 
 
 Install each dependency that is not installed on your host. For Debian/Ubuntu
-distributions, execute the following:
+distributions, run the following commands:
 
 .. prompt:: bash $
 
        sudo apt-get install gcc python-dev python3-pip libxml2-dev libxslt-dev doxygen graphviz ant ditaa
        sudo apt-get install python3-sphinx python3-venv cython3
 
-For Fedora distributions, execute the following:
+For Fedora distributions, run the following commands:
 
 .. prompt:: bash $
 
@@ -366,25 +368,26 @@ For Fedora distributions, execute the following:
    sudo yum install python-jinja2 python-pygments python-docutils python-sphinx
    sudo yum install jericho-html ditaa
 
-For CentOS/RHEL distributions, it is recommended to have ``epel`` (Extra
-Packages for Enterprise Linux) repository as it provides some extra packages
-which are not available in the default repository. To install ``epel``, execute
-the following:
+For CentOS/RHEL distributions, it is recommended to enable the ``epel`` (Extra
+Packages for Enterprise Linux) repository, because it provides extra packages
+not available in the default repository. To install ``epel``, run the following
+command:
 
 .. prompt:: bash $
 
-        sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
+   sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
 
-For CentOS/RHEL distributions, execute the following:
+For CentOS/RHEL distributions, run the following commands:
 
 .. prompt:: bash $
 
-       sudo yum install gcc python-devel python-pip libxml2-devel libxslt-devel doxygen graphviz ant
-       sudo pip install html2text
+   sudo yum install gcc python-devel python-pip libxml2-devel libxslt-devel doxygen graphviz ant
+   sudo pip install html2text
 
-For CentOS/RHEL distributions, the remaining python packages are not available
-in the default and ``epel`` repositories. So, use http://rpmfind.net/ to find
-the packages. Then, download them from a mirror and install them. For example:
+For CentOS/RHEL distributions, the remaining Python packages are not available
+in the default repositories or  the ``epel`` repositories. Use
+http://rpmfind.net/ to find the packages. Then download them from a mirror and
+install them. For example:
 
 .. prompt:: bash $
 
@@ -397,19 +400,19 @@ the packages. Then, download them from a mirror and install them. For example:
        wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-sphinx-1.1.3-11.el7.noarch.rpm
        sudo yum install python-sphinx-1.1.3-11.el7.noarch.rpm
 
-Ceph documentation makes extensive use of `ditaa`_, which is not presently built
-for CentOS/RHEL7. You must install ``ditaa`` if you are making changes to
-``ditaa`` diagrams so that you can verify that they render properly before you
-commit new or modified ``ditaa`` diagrams. You may retrieve compatible required
-packages for CentOS/RHEL distributions and install them manually. To run
-``ditaa`` on CentOS/RHEL7, following dependencies are required:
+Ceph documentation makes extensive use of `ditaa`_, which is not built for
+CentOS/RHEL. If you make changes to ``ditaa`` diagrams, you must install
+``ditaa`` to verify that they render properly before you commit your changes.
+You may retrieve compatible required packages for CentOS/RHEL distributions and
+install them manually. To run ``ditaa`` on CentOS/RHEL, following dependencies
+are required:
 
 - jericho-html
 - jai-imageio-core
 - batik
 
-Use http://rpmfind.net/ to find compatible ``ditaa`` and the dependencies.
-Then, download them from a mirror and install them. For example:
+Use http://rpmfind.net/ to find compatible ``ditaa`` and its dependencies.
+Then download them from a mirror and install them. For example:
 
 .. prompt:: bash $
 
@@ -422,8 +425,8 @@ Then, download them from a mirror and install them. For example:
        wget http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/d/ditaa-0.9-13.r74.fc21.noarch.rpm
        sudo yum install ditaa-0.9-13.r74.fc21.noarch.rpm
 
-Once you have installed all these packages, build the documentation by following
-the steps given in `Build the Source`_.
+After you have installed these packages, build the documentation by following
+the steps in `Build the Source`_.
 
 
 Commit the Change