From 5149e8c7688eab1fb56009cded6d5f80411bb8a9 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Tue, 11 Aug 2015 11:12:26 +0200 Subject: [PATCH] DOC: add guideline to use versionadded directive to contributing docs (GH10215) --- doc/source/contributing.rst | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 7df5a18959ba7..4ec2258df56f2 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -247,6 +247,8 @@ just checked out. There are two primary methods of doing this. from your development directory. Thus, you can always be using the development version on your system without being inside the clone directory. +.. _contributing.documentation: + Contributing to the documentation ================================= @@ -543,10 +545,23 @@ Documenting your code Changes should be reflected in the release notes located in `doc/source/whatsnew/vx.y.z.txt`. This file contains an ongoing change log for each release. Add an entry to this file to document your fix, enhancement or (unavoidable) breaking change. Make sure to include the -GitHub issue number when adding your entry. +GitHub issue number when adding your entry (using `` :issue:`1234` `` where `1234` is the +issue/pull request number). + +If your code is an enhancement, it is most likely necessary to add usage +examples to the existing documentation. This can be done following the section +regarding documentation :ref:`above `. +Further, to let users know when this feature was added, the ``versionadded`` +directive is used. The sphinx syntax for that is: + +.. code-block:: rst + + .. versionadded:: 0.17.0 -If your code is an enhancement, it is most likely necessary to add usage examples to the -existing documentation. This can be done following the section regarding documentation. +This will put the text *New in version 0.17.0* wherever you put the sphinx +directive. This should also be put in the docstring when adding a new function +or method (`example `__) +or a new keyword argument (`example `__). Contributing your changes to *pandas* =====================================