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
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
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}
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
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
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
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
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
Signed-off-by: John Doe <john.doe@gmail.com>
-To commit changes, execute the following::
+To commit changes, execute the following:
+
+.. prompt:: bash $
git commit -a
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
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
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
projects / ceph.git / commitdiff