# Writing documentation

## Types of documentation

- Tutorials: take a reader unfamiliar with pydicom through a series of steps to achieve something useful
- How-to/examples: more advanced versions of tutorials, for readers that already have some understanding of how pydicom works
- Guides: aim to explain a subject at a fairly high level
- Reference: contain technical reference information for the pydicom API for a reader that has some familiarity with pydicom but needs to learn or be reminded about a specific part of it

## General style guidelines

- pydicom - italicized lowercase: pydicom
- DICOM, DICOM Standard - uppercase DICOM, and S on Standard
- Python - capitalize Python
- itemize, etc - use the American English spelling
- (7FE0,0010) Pixel Data - use uppercase hex, no space between the comma and element number, and italicize the element name, e.g. (7FE0,0010) Pixel Data. When referring to an element name by itself then use italics: Bits Allocated
- ds, elem, seq, arr - when writing examples try to use `ds` as the variable name for `Dataset`, `elem` for `DataElement`, `seq` for sequences and `arr` for numpy arrays.
- them, they, their - use gender neutral pronouns when referring to a hypothetical person
- Use the double back-tick markup ``0xB4`` when referring to:
  - A Python built-in value such as `True`, `False`, `None`
  - When referring to a value passed by a parameter: If fragments_per_frame is not `1` then…
  - When writing a hex value `0xB4`
  - When referring to a class, function, variable, etc and you haven’t used semantic markup: `Dataset` when not using `Dataset`
- Use a single back-tick `italics` for parameter names: If fragments_per_frame is not…
- For the API reference documentation, follow the NumPy docstring guide

## Guidelines for reStructuredText

- In section titles, capitalize only initial words and proper nouns

- Documentation should be wrapped at 80 characters unless there’s a good reason not to

- Because Sphinx will automatically link to the corresponding API documentation, the more semantic markup you can add, the better. So this:

      :attr:`Dataset.pixel_array<pydicom.dataset.Dataset.pixel_array>` returns a :class:`numpy.ndarray`

  which produces: “`Dataset.pixel_array` returns a `numpy.ndarray`”, is better than this:

      ``Dataset.pixel_array`` returns a numpy ``ndarray``

  which produces: “`Dataset.pixel_array` returns a numpy `ndarray`”

- Targets can be prefixed with ~ so that the last bit of the path gets used as the link title. So `:class:`~pydicom.dataset.Dataset`` will show as a `Dataset`.

- Python and NumPy objects can also be referenced: `:class:`float``, `:class:`numpy.dtype``

- Use `:dcm:` to link to the CHTML version of the DICOM Standard. For example, `:dcm:`this section<part05/sect_6.2.html>`` will link to this section of the Standard. The link target should be the part of the URL after `http://dicom.nema.org/medical/dicom/current/output/chtml/`

- Use these heading styles:

      ===
      One
      ===

      Two
      ===

      Three
      -----

      Four
      ~~~~

      Five
      ^^^^

- Use `.. note::` and `.. warning::` and similar boxes sparingly

- New features should be documented with `.. versionadded:: X.Y` at the top of the first section and changes to existing features with `..versionchanged:: X.Y` at the bottom of the first section:

      .. versionchanged:: 1.4

          The ``handler`` keyword argument was added