<commit_before>.. _documentation-guidelines:

*********************
Writing Documentation
*********************

High-quality, consistent documentation for astronomy code is one of the major
goals of the Astropy Project.  Hence, we describe our documentation procedures
and rules here.  For the astropy core project and coordinated packages we try to
keep to these as closely as possible, and we encourage affiliated packages to
also adhere to these as they encourage useful documentation, a characteristic
often lacking in professional astronomy software.

Adding a Git commit
===================

When your changes only affect documentation (i.e., docstring or RST files)
and do not include any code snippets that require doctest to run, you may
add a ``[skip travis]`` in your commit message. For example::

    git commit -m "Update documentation about this and that [skip travis]"

When this commit is pushed out to your branch associated with a pull request,
Travis CI will be skipped because it is not required. This is because the
CI job to build the documentation resides in CircleCI.

This special ``[skip travis]`` directive is being handled by ``ci-helpers``
that Astropy uses for its continuous integration.

Building the Documentation from source
======================================

For information about building the documentation from source, see
the :ref:`builddocs` section in the installation instructions.

Astropy Documentation Rules and Guidelines
==========================================

This section describes the standards for documentation that any contribution
being considered for integration into the core package should follow, as well as
the standard Astropy docstring format.

* All documentation text should follow the :ref:`astropy-style-guide`.

* All documentation should be written use the `Sphinx`_<commit_msg>Apply review from @bsipocz<commit_after>.. _documentation-guidelines:

*********************
Writing Documentation
*********************

High-quality, consistent documentation for astronomy code is one of the major
goals of the Astropy Project.  Hence, we describe our documentation procedures
and rules here.  For the astropy core project and coordinated packages we try to
keep to these as closely as possible, and we encourage affiliated packages to
also adhere to these as they encourage useful documentation, a characteristic
often lacking in professional astronomy software.

Adding a Git commit
===================

When your changes only affect documentation (i.e., docstring or RST files)
and do not include any code snippets that require doctest to run, you may
add a ``[skip travis]`` in your commit message. For example::

    git commit -m "Update documentation about this and that [skip travis]"

When this commit is pushed out to your branch associated with a pull request,
Travis CI will be skipped because it is not required. This is because the
CI job to build the documentation resides in CircleCI.


Building the Documentation from source
======================================

For information about building the documentation from source, see
the :ref:`builddocs` section in the installation instructions.

Astropy Documentation Rules and Guidelines
==========================================

This section describes the standards for documentation that any contribution
being considered for integration into the core package should follow, as well as
the standard Astropy docstring format.

* All documentation text should follow the :ref:`astropy-style-guide`.

* All documentation should be written use the `Sphinx`_
{'fraction_non_alphanumeric': 0.11370586599944398, 'fraction_numerical': 0.0, 'mean_word_length': 5.413547237076648, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2948663', 'n_tokens_mistral': 816, 'n_tokens_neox': 763, 'n_words': 471}