# Contributing a documentation change

This tutorial will take you through the process of:

- Downloading the current documentation

- Installing required libraries

- Building and previewing the documentation

- Creating a new git branch

- Making a change to the documentation

- Committing the changes and making a pull request

## Download the documentation

1. Sign up to GitHub and fork pydicom

2. Install Git. If you’re new to Git, the Django project has a good introduction on working with Git and GitHub. You can also take a look at the GitHub branch-based workflow

3. Using the command line, `cd` to the directory where you want your local copy of pydicom to live. The documentation can then be downloaded using:

       $ git clone https://github.com/YourUsername/pydicom.git

4. (Optional) We recommend that you install your development copy of pydicom in a virtual environment. See the virtual environments tutorial for more information.

   Create a new virtualenv `pyd-doc`, using a Python 3.X version such as 3.7:

       $ mkvirtualenv -p /path/to/python3.7 pyd-doc

5. Install the cloned copy of pydicom (`-e` for editable mode):

       $ pip install -e pydicom/

## Install required libraries

    $ pip install sphinx sphinx-rtd-theme sphinx-gallery sphinx-issues sphinx-copybutton

## Build and preview the documentation

pydicom’s documentation consists of a series of reStructuredText (reST) files located in the project’s `pydicom/doc` directory which are converted to HTML using Sphinx during our build process. To build the documentation locally, navigate to the `doc` directory and run `make html`:

    $ cd pydicom/doc
    $ make html

Occasionally you may need to clean up the generated files before a change gets applied:

    $ make clean && make html

The HTML generated by the build can be viewed by opening `_build/html/index.html` in a web browser or by doing:

    $ cd _build/html
    $ python -m http.server 9999

And then going to http://localhost:9999

## Create a new branch

Create a new branch `doc-tut` for your changes (you can choose any name that you want instead). Any changes made in this branch will be specific to it and won’t affect the main copy (the `master` branch) of the documentation:

    $ git checkout -b doc-tut

## Make a change to the documentation

Let’s add a new guide on how to read a DICOM file. Create a new `reading.rst` file in `doc/tutorials`, open it in a text editor and add in a title and some text:

    ===================
    Reading DICOM files
    ===================

    In this tutorial we will be reading a DICOM file using *pydicom*.

Save it and build the documentation (`make html`). You should see a warning in the build output, which we’ll ignore for now:

    checking consistency... [/path/to]/pydicom/doc/tutorials/reading.rst: WARNING: document isn't included in any toctree

Open the file `_build/html/tutorials/reading.html` in your browser (if you’re not using the Python `http.server` command) or here (if you are). Your new page should be visible.

The reason we got the warning above is because the page itself hasn’t been included in Sphinx’s table of contents (the `toctree`), which Sphinx uses to map the relationship between pages in the documentation. It’s not a requirement that a page be included in the `toctree`, but it’s a good idea.

To make our new page a bit easier to find we’ll include a link to it in `tutorials/index.rst`, which will also include it in the `toctree`:

    .. toctree::
       :maxdepth: 1

       installation
       virtualenvs
       contributing_code
       contributing_docs
       reading

If you rebuild the HTML you should find that the warning is gone and that your new page is reachable from the main documentation page (on the left under “Documentation”: Tutorials → Reading DICOM files).

Next we’ll expand our page a bit to show off how to use some of the reST markup:

    ===================
    Reading DICOM files
    ===================

    In this tutorial we will be reading a DICOM file using
    `pydicom <https://github.com/pydicom/pydicom>`_. The tasks you'll be doing
    will include:

    * Installing *pydicom*
    * Reading a :dcm:`DICOM dataset<part05/chapter_7.html>`
    * Printing an element

    Installing pydicom
    ==================
    See the :doc:`Installation guide</tutorials/installation>` on how to install
    *pydicom*.

    Reading a DICOM dataset
    =======================
    In a command window start a new **Python** session::

      $ python
      Python 3.6.5 (default, Apr  1 2018, 05:46:30)
      [GCC 7.3.0] on linux
      Type "help", "copyright", "credits" or "license" for more information.

    .. note::

      Your Python version may be different

    *pydicom* includes a number of files which can be accessed through the
    :func:`~pydicom.data.get_testdata_file` function. To read the file
    ``CT_small.dcm`` we use :func:`~pydicom.filereader.dcmread`::

      >>> from pydicom import dcmread
      >>> from pydicom.data import get_testdata_file
      >>> fpath = get_testdata_file("CT_small.dcm")
      >>> fpath
      '[path/to]/pydicom/data/test_files/CT_small.dcm'
      >>> ds = dcmread(fpath)

    Printing an element
    ===================
    To get a :class:`list` of keywords for all the elements in the top level of
    the dataset you can do:

      >>> ds.dir()
      ['AccessionNumber', 'AcquisitionData', ..., 'PatientName', ..., 'XRayTubeCurrent']

    To :func:`print` the value of the (0010,0010) *Patient Name* element:

      >>> print(ds.PatientName)
      CompressedSamples^CT1

    To print the element itself:

      >>> print(ds['PatientName'])
      (0010, 0010) Patient's Name                      PN: 'CompressedSamples^CT1'

If you need help with the reST markup then you can:

- Take a look at the existing documentation to see how it was created

- Check out Sphinx’s reStructuredText primer

There are also a number of directives that tell Sphinx to do certain things (like inserting code blocks or a table of contents). Sphinx has a list of these here.

For more information on writing documentation for pydicom, see writing documentation.

Just like before, you should build and preview the updated page. When you’re happy with the results move on to the next section.

## Commit your changes and make a pull request

First we add our new file to git:

    $ git add tutorials/reading.rst

And then stage the remaining changes (`-a`) and commit at the same time:

    $ git commit -am "Add documentation on reading a DICOM file"

After committing the changes, send them to your fork:

    $ git push origin doc-tut

You can create a pull request by visiting the pydicom GitHub page where you should see your branch under “Your recently push branches”. Click “Compare & pull request” and fill out the title (with a `[WIP]` prefix, i.e. `[WIP] Add documentation of reading a DICOM file`) and follow the instructions in the main entry window.

To submit the pull request (PR) for real - please don’t do this for this example! - then on the next page you would click “Create pull request”. Creating the PR would automatically start the documentation build checks which would be visible at the bottom of the PR as the CircleCI check. Depending on when you view it, the check would either be in progress, have passed or failed. The details of the CircleCI build could be seen by clicking on “Details”

If the build was successful then the Artifacts tab would be visible (which may require signing into CircleCI). The artifacts are the generated HTML files and can be used to preview the results of the build by clicking Artifacts → `circleci/project/doc/_build/html/index.html`

If all the checks passed and you were happy with your changes, you’d change the PR title prefix to `[MRG]`. This would indicate that you considered the PR ready to be reviewed and merged into the main branch.

## What happens next?

One or more reviewers would look at your pull request and may make suggestions, ask for clarification or request changes. Once the reviewers were happy, the pull request would be approved and your changes merged into the `master` branch where they would become part of pydicom.

However, because this is just an example, all we’re going to do is clean up the changes we’ve made. First we switch back to the `master` branch:

    $ git checkout master

We delete the local copy of the branch we created:

    $ git branch -d doc-tut

And lastly we delete the remote copy on GitHub. Go to `https://github.com/YourUsername/pydicom/branches`, find the `doc-tut` branch and click the corresponding red bin icon. All done!