From: Zac Dover Date: Sat, 14 Nov 2020 07:22:35 +0000 (+1000) Subject: doc/start: update prompts in documenting-ceph.rst X-Git-Tag: v16.1.0~456^2 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=2b90e77802afbcea2a14e441046c6fa8b2e0059d;p=ceph.git doc/start: update prompts in documenting-ceph.rst This commit adds the ".. prompt:: bash $" directive to the commands in "documenting-ceph.rst" so that the permissions level of each command is evident (through the presentation of the $ or the #), and so that when the reader cuts and pastes the commands from the documentation, they don't have to delete the prompt (because that's how this directive renders). This commit also instructs the reader to add the directory containing "build-doc" and "serve-doc" to the PATH environment variable in order to run the commands. Signed-off-by: Zac Dover Co-authored-by: Kefu Chai --- diff --git a/doc/start/documenting-ceph.rst b/doc/start/documenting-ceph.rst index f345302f8af4..fa528a647375 100644 --- a/doc/start/documenting-ceph.rst +++ b/doc/start/documenting-ceph.rst @@ -43,25 +43,35 @@ see :ref:`Get Involved`. The most common way to make contributions is to use the `Fork and Pull`_ approach. You must: -#. Install git locally. For Debian/Ubuntu, execute:: +#. Install git locally. For Debian/Ubuntu, execute: + + .. prompt:: bash $ sudo apt-get install git - For Fedora, execute:: + For Fedora, execute: + + .. prompt:: bash $ sudo yum install git - For CentOS/RHEL, execute:: + For CentOS/RHEL, execute: + + .. prompt:: bash $ sudo yum install git -#. Ensure your ``.gitconfig`` file has your name and email address. :: +#. Ensure your ``.gitconfig`` file has your name and email address. : + + .. code-block:: ini [user] email = {your-email-address} name = {your-name} - For example:: + For example: + + .. prompt:: bash $ git config --global user.name "John Doe" git config --global user.email johndoe@example.com @@ -110,12 +120,16 @@ Select a Branch When you make small changes to the documentation, such as fixing typographical errors or clarifying explanations, use the ``master`` branch (default). You should also use the ``master`` branch when making contributions to features that -are in the current release. ``master`` is the most commonly used branch. :: +are in the current release. ``master`` is the most commonly used branch. : + +.. prompt:: bash $ git checkout master When you make changes to documentation that affect an upcoming release, use -the ``next`` branch. ``next`` is the second most commonly used branch. :: +the ``next`` branch. ``next`` is the second most commonly used branch. : + +.. prompt:: bash $ git checkout next @@ -139,11 +153,15 @@ http://tracker.ceph.com/issues/4000. describing the relevant changes/options. Before you create your branch name, ensure that it doesn't already exist in the -local or remote repository. :: +local or remote repository. : + +.. prompt:: bash $ git branch -a | grep wip-doc-{your-branch-name} -If it doesn't exist, create your branch:: +If it doesn't exist, create your branch: + +.. prompt:: bash $ git checkout -b wip-doc-{your-branch-name} @@ -166,12 +184,16 @@ Your new document doesn't get tracked by ``git`` automatically. When you want to add the document to the repository, you must use ``git add {path-to-filename}``. For example, from the top level directory of the repository, adding an ``example.rst`` file to the ``rados`` subdirectory would -look like this:: +look like this: + +.. prompt:: bash $ git add doc/rados/example.rst Deleting a document involves removing it from the repository with ``git rm -{path-to-filename}``. For example:: +{path-to-filename}``. For example: + +.. prompt:: bash $ git rm doc/rados/example.rst @@ -181,33 +203,49 @@ You must also remove any reference to a deleted document from other documents. Build the Source ---------------- -To build the documentation, navigate to the ``ceph`` repository directory:: +To build the documentation, navigate to the ``ceph`` repository directory: + + +.. prompt:: bash $ cd ceph -To build the documentation on Debian/Ubuntu, Fedora, or CentOS/RHEL, execute:: +.. note:: + The directory that contains ``build-doc`` and ``serve-doc`` must be included + in the ``PATH`` environment variable in order for these commands to work. + + +To build the documentation on Debian/Ubuntu, Fedora, or CentOS/RHEL, execute: + +.. prompt:: bash $ admin/build-doc -To scan for the reachability of external links, execute:: +To scan for the reachability of external links, execute: + +.. prompt:: bash $ admin/build-doc linkcheck -Executing ``admin/build-doc`` will create a ``build-doc`` directory under ``ceph``. -You may need to create a directory under ``ceph/build-doc`` for output of Javadoc -files. :: +Executing ``admin/build-doc`` will create a ``build-doc`` directory under +``ceph``. You may need to create a directory under ``ceph/build-doc`` for +output of Javadoc files: + +.. prompt:: bash $ mkdir -p output/html/api/libcephfs-java/javadoc The build script ``build-doc`` will produce an output of errors and warnings. -You MUST fix errors in documents you modified before committing a change, and you -SHOULD fix warnings that are related to syntax you modified. +You MUST fix errors in documents you modified before committing a change, and +you SHOULD fix warnings that are related to syntax you modified. .. important:: You must validate ALL HYPERLINKS. If a hyperlink is broken, it automatically breaks the build! Once you build the documentation set, you may start an HTTP server at -``http://localhost:8080/`` to view it:: +``http://localhost:8080/`` to view it: + +.. prompt:: bash $ admin/serve-doc @@ -287,12 +325,16 @@ the following packages are required: Install each dependency that is not installed on your host. For Debian/Ubuntu -distributions, execute the following:: +distributions, execute the following: + +.. prompt:: bash $ sudo apt-get install gcc python-dev python-pip python-virtualenv libxml2-dev libxslt-dev doxygen graphviz ant ditaa sudo apt-get install python-sphinx -For Fedora distributions, execute the following:: +For Fedora distributions, execute the following: + +.. prompt:: bash $ sudo yum install gcc python-devel python-pip python-virtualenv libxml2-devel libxslt-devel doxygen graphviz ant sudo pip install html2text @@ -302,18 +344,24 @@ For Fedora distributions, execute the following:: 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:: +the following: + +.. prompt:: bash $ 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, execute the following: + +.. prompt:: bash $ sudo yum install gcc python-devel python-pip python-virtualenv 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 and ``epel`` repositories. So, use http://rpmfind.net/ to find +the packages. Then, download them from a mirror and install them. For example: + +.. prompt:: bash $ wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-jinja2-2.7.2-2.el7.noarch.rpm sudo yum install python-jinja2-2.7.2-2.el7.noarch.rpm @@ -328,15 +376,17 @@ 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: +packages for CentOS/RHEL distributions and install them manually. To run +``ditaa`` on CentOS/RHEL7, 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:: +Then, download them from a mirror and install them. For example: + +.. prompt:: bash $ wget http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/j/jericho-html-3.3-4.fc22.noarch.rpm sudo yum install jericho-html-3.3-4.fc22.noarch.rpm @@ -398,7 +448,9 @@ There is a carriage return between the summary line and the description:: Signed-off-by: John Doe -To commit changes, execute the following:: +To commit changes, execute the following: + +.. prompt:: bash $ git commit -a @@ -410,15 +462,21 @@ your uncommitted changes, staging them for commit, committing the changes and pushing them to your forked Ceph repository. -For Debian/Ubuntu, execute:: +For Debian/Ubuntu, execute: + +.. prompt:: bash $ sudo apt-get install gitk git-gui -For Fedora/CentOS/RHEL, execute:: +For Fedora/CentOS/RHEL, execute: + +.. prompt:: bash $ sudo yum install gitk git-gui -Then, execute:: +Then, execute: + +.. prompt:: bash $ cd {git-ceph-repo-path} gitk @@ -431,11 +489,15 @@ Push the Change Once you have one or more commits, you must push them from the local copy of the repository to ``github``. A graphical tool like ``git-gui`` provides a user -interface for pushing to the repository. If you created a branch previously:: +interface for pushing to the repository. If you created a branch previously: + +.. prompt:: bash $ git push origin wip-doc-{your-branch-name} -Otherwise:: +Otherwise: + +.. prompt:: bash $ git push @@ -463,7 +525,9 @@ the documentation in both native restructuredText format and its rendered formats such as HTML. Navigate to your Ceph repository and view a document in its native format. You may notice that it is generally as legible in a terminal as it is in its rendered HTML format. Additionally, you may also notice that -diagrams in ``ditaa`` format also render reasonably well in text mode. :: +diagrams in ``ditaa`` format also render reasonably well in text mode. : + +.. prompt:: bash $ less doc/architecture.rst