From 29e2c9f62ee85ce01f583a19e5a91eda2a100949 Mon Sep 17 00:00:00 2001 From: Zac Dover Date: Sat, 22 Apr 2023 09:03:12 +0200 Subject: [PATCH] doc/start: edit first 50 lines of documenting-ceph Edit the first 150 lines of doc/start/documenting-ceph.rst. This is part of an initiative to harvest the fruits of Cephalocon 2023, at which documentation proved to be in demand to a surprising degree. Co-authored-by: Anthony D'Atri Signed-off-by: Zac Dover (cherry picked from commit dd37f94aa4f1de947b1eaf5d82cc529925f5823e) --- doc/start/documenting-ceph.rst | 65 ++++++++++++++++------------------ 1 file changed, 31 insertions(+), 34 deletions(-) diff --git a/doc/start/documenting-ceph.rst b/doc/start/documenting-ceph.rst index 4c8dca84208..3158f8a6ad5 100644 --- a/doc/start/documenting-ceph.rst +++ b/doc/start/documenting-ceph.rst @@ -2,11 +2,8 @@ Documenting Ceph ================== -The **easiest way** to help the Ceph project is to contribute to the -documentation. As the Ceph user base grows and the development pace quickens, an -increasing number of people are updating the documentation and adding new -information. Even small contributions like fixing spelling errors or clarifying -instructions will help the Ceph project immensely. +You can help the Ceph project by contributing to the documentation. Even +small contributions help the Ceph project. The Ceph documentation source resides in the ``ceph/doc`` directory of the Ceph repository, and Python Sphinx renders the source into HTML and manpages. The @@ -47,10 +44,10 @@ branch name you prefer (for example, ``pacific``, to create a URL that reads Making Contributions ==================== -Making a documentation contribution generally involves the same procedural -sequence as making a code contribution, except that you must build documentation -source instead of compiling program source. The sequence includes the following -steps: +Making a documentation contribution involves the same basic procedure as making +a code contribution, with one exception: you must build documentation source +instead of compiling program source. This sequence (the sequence of building +the documentation source) includes the following steps: #. `Get the Source`_ #. `Select a Branch`_ @@ -64,32 +61,33 @@ steps: Get the Source -------------- -Ceph documentation lives in the Ceph repository right alongside the Ceph source -code under the ``ceph/doc`` directory. For details on github and Ceph, -see :ref:`Get Involved`. +The source of the Ceph documentation is a collection of ReStructured Text files +that are in the Ceph repository in the ``ceph/doc`` directory. For details +on GitHub and Ceph, see :ref:`Get Involved`. -The most common way to make contributions is to use the `Fork and Pull`_ -approach. You must: +Use the `Fork and Pull`_ approach to make documentation contributions. To do +this, you must: -#. Install git locally. For Debian/Ubuntu, execute: +#. Install git locally. In Debian or Ubuntu, run the following command: .. prompt:: bash $ sudo apt-get install git - For Fedora, execute: + In Fedora, run the following command: .. prompt:: bash $ sudo yum install git - For CentOS/RHEL, execute: + In CentOS/RHEL, run the following command: .. prompt:: bash $ sudo yum install git -#. Ensure your ``.gitconfig`` file has your name and email address. : +#. Make sure that your ``.gitconfig`` file has been configured to include your + name and email address: .. code-block:: ini @@ -109,37 +107,36 @@ approach. You must: #. Fork the Ceph project. See https://github.com/ceph/ceph. -#. Clone your fork of the Ceph project to your local host. +#. Clone your fork of the Ceph project to your local host. This creates what is + known as a "local working copy". +The Ceph documentation is organized by component: -Ceph organizes documentation into an information architecture primarily by its -main components. - -- **Ceph Storage Cluster:** The Ceph Storage Cluster documentation resides - under the ``doc/rados`` directory. +- **Ceph Storage Cluster:** The Ceph Storage Cluster documentation is + in the ``doc/rados`` directory. -- **Ceph Block Device:** The Ceph Block Device documentation resides under +- **Ceph Block Device:** The Ceph Block Device documentation is in the ``doc/rbd`` directory. -- **Ceph Object Storage:** The Ceph Object Storage documentation resides under +- **Ceph Object Storage:** The Ceph Object Storage documentation is in the ``doc/radosgw`` directory. -- **Ceph File System:** The Ceph File System documentation resides under the +- **Ceph File System:** The Ceph File System documentation is in the ``doc/cephfs`` directory. -- **Installation (Quick):** Quick start documentation resides under the +- **Installation (Quick):** Quick start documentation is in the ``doc/start`` directory. -- **Installation (Manual):** Manual installation documentation resides under - the ``doc/install`` directory. +- **Installation (Manual):** Documentaton concerning the manual installation of + Ceph is in the ``doc/install`` directory. -- **Manpage:** Manpage source resides under the ``doc/man`` directory. +- **Manpage:** Manpage source is in the ``doc/man`` directory. -- **Developer:** Developer documentation resides under the ``doc/dev`` +- **Developer:** Developer documentation is in the ``doc/dev`` directory. -- **Images:** If you include images such as JPEG or PNG files, you should - store them under the ``doc/images`` directory. +- **Images:** Images including JPEG and PNG files are stored in the + ``doc/images`` directory. Select a Branch -- 2.47.3