From d4848fccc2a8c5f38846a81ab1060498fe1b62a9 Mon Sep 17 00:00:00 2001 From: Sourav Singh Date: Sat, 25 Feb 2017 23:38:35 +0530 Subject: [PATCH 1/9] Create docstrings.rst --- .../contributing/strategy/docstrings.rst | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 docs/tutorials/contributing/strategy/docstrings.rst diff --git a/docs/tutorials/contributing/strategy/docstrings.rst b/docs/tutorials/contributing/strategy/docstrings.rst new file mode 100644 index 000000000..56ad73c75 --- /dev/null +++ b/docs/tutorials/contributing/strategy/docstrings.rst @@ -0,0 +1,55 @@ +Writing docstrings +================== + +The project takes pride in its documentation for the strategies +and its corresponding bibliography. The docstring is a string +which describes a method, module or class. The docstrings help +the user in understanding the working of the strategy +and the source of the strategy. The docstring must be written in +the following way, i.e.:: + + """This is a docstring. + + It can be written over multiple lines. + + """ + +Sections +-------- + +The Sections of the docstring are: + +1. **Working of the strategy** + + A brief summary on how the strategy works, E.g. + + :: + + class TitForTat(Player): + """ + A player starts by cooperating and then mimics the + previous action of the opponent. + """ + +2. **Bibliography/Source of the strategy** + + A section to mention the source of the strategy + or the paper from which the strategy was taken. + The section must start with the """Names:""". + For E.g. + + :: + + class TitForTat(Player): + """ + A player starts by cooperating and then mimics the + previous action of the opponent. + + Names: + - Rapoport's strategy: [Axelrod1980]_ + - TitForTat: [Axelrod1980]_ + """ + + Here,the info written under thr Names section + tells about the source of the TitforTat strategy. + From b2306854635291c82648ab2338ae1b9273a63a77 Mon Sep 17 00:00:00 2001 From: Sourav Singh Date: Sat, 25 Feb 2017 23:40:11 +0530 Subject: [PATCH 2/9] Add links to Index --- docs/tutorials/contributing/strategy/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/tutorials/contributing/strategy/index.rst b/docs/tutorials/contributing/strategy/index.rst index fffc28bbe..98eb1709a 100644 --- a/docs/tutorials/contributing/strategy/index.rst +++ b/docs/tutorials/contributing/strategy/index.rst @@ -11,6 +11,7 @@ Contents: instructions.rst writing_the_new_strategy.rst + docstrings.rst adding_the_new_strategy.rst classifying_the_new_strategy.rst writing_test_for_the_new_strategy.rst From bb9eea201b36973a193376fe57a19dea691a9c0e Mon Sep 17 00:00:00 2001 From: Sourav Singh Date: Sun, 26 Feb 2017 16:07:43 +0530 Subject: [PATCH 3/9] Update docstrings.rst --- .../contributing/strategy/docstrings.rst | 34 ++++++++----------- 1 file changed, 15 insertions(+), 19 deletions(-) diff --git a/docs/tutorials/contributing/strategy/docstrings.rst b/docs/tutorials/contributing/strategy/docstrings.rst index 56ad73c75..4483e11cd 100644 --- a/docs/tutorials/contributing/strategy/docstrings.rst +++ b/docs/tutorials/contributing/strategy/docstrings.rst @@ -21,34 +21,30 @@ The Sections of the docstring are: 1. **Working of the strategy** - A brief summary on how the strategy works, E.g. - - :: + A brief summary on how the strategy works, E.g.:: - class TitForTat(Player): - """ - A player starts by cooperating and then mimics the - previous action of the opponent. - """ + class TitForTat(Player): + """ + A player starts by cooperating and then mimics the + previous action of the opponent. + """ 2. **Bibliography/Source of the strategy** A section to mention the source of the strategy or the paper from which the strategy was taken. The section must start with the """Names:""". - For E.g. - - :: + For E.g.:: - class TitForTat(Player): - """ - A player starts by cooperating and then mimics the - previous action of the opponent. + class TitForTat(Player): + """ + A player starts by cooperating and then mimics the + previous action of the opponent. - Names: - - Rapoport's strategy: [Axelrod1980]_ - - TitForTat: [Axelrod1980]_ - """ + Names: + - Rapoport's strategy: [Axelrod1980]_ + - TitForTat: [Axelrod1980]_ + """ Here,the info written under thr Names section tells about the source of the TitforTat strategy. From f4fafa11b54f0106d45a10ac206581aebaf8f5d5 Mon Sep 17 00:00:00 2001 From: Sourav Singh Date: Sun, 26 Feb 2017 16:09:00 +0530 Subject: [PATCH 4/9] Fix errors and formatting --- docs/tutorials/contributing/strategy/docstrings.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/tutorials/contributing/strategy/docstrings.rst b/docs/tutorials/contributing/strategy/docstrings.rst index 4483e11cd..018ff9f5b 100644 --- a/docs/tutorials/contributing/strategy/docstrings.rst +++ b/docs/tutorials/contributing/strategy/docstrings.rst @@ -21,7 +21,7 @@ The Sections of the docstring are: 1. **Working of the strategy** - A brief summary on how the strategy works, E.g.:: + A brief summary on how the strategy works, E.g.:: class TitForTat(Player): """ @@ -31,10 +31,10 @@ The Sections of the docstring are: 2. **Bibliography/Source of the strategy** - A section to mention the source of the strategy - or the paper from which the strategy was taken. - The section must start with the """Names:""". - For E.g.:: + A section to mention the source of the strategy + or the paper from which the strategy was taken. + The section must start with the Names section. + For E.g.:: class TitForTat(Player): """ From 1ad1c6f011d9640baf60e9bee2fcecfdff8ce470 Mon Sep 17 00:00:00 2001 From: Sourav Singh Date: Sun, 26 Feb 2017 16:09:49 +0530 Subject: [PATCH 5/9] Fix formatting with Bibliography section --- docs/tutorials/contributing/strategy/docstrings.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/contributing/strategy/docstrings.rst b/docs/tutorials/contributing/strategy/docstrings.rst index 018ff9f5b..5eb0a03ce 100644 --- a/docs/tutorials/contributing/strategy/docstrings.rst +++ b/docs/tutorials/contributing/strategy/docstrings.rst @@ -46,6 +46,6 @@ The Sections of the docstring are: - TitForTat: [Axelrod1980]_ """ - Here,the info written under thr Names section - tells about the source of the TitforTat strategy. + Here,the info written under thr Names section + tells about the source of the TitforTat strategy. From c06c4cbca3eca19cf93e75d4e4a8b80811c0dd07 Mon Sep 17 00:00:00 2001 From: Sourav Singh Date: Sun, 26 Feb 2017 20:58:14 +0530 Subject: [PATCH 6/9] Update docstrings.rst --- .../contributing/strategy/docstrings.rst | 20 ++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/contributing/strategy/docstrings.rst b/docs/tutorials/contributing/strategy/docstrings.rst index 5eb0a03ce..a3a39c069 100644 --- a/docs/tutorials/contributing/strategy/docstrings.rst +++ b/docs/tutorials/contributing/strategy/docstrings.rst @@ -46,6 +46,24 @@ The Sections of the docstring are: - TitForTat: [Axelrod1980]_ """ - Here,the info written under thr Names section + Here,the info written under the Names section tells about the source of the TitforTat strategy. + `[Axelrod1980]_` corresponds to the bibliographic item in + `docs/reference/bibliography.rst`. If you are using a source + that is not in the bibliography please add it. + + If you are using a software code as a source of the startegy, + please cite the name of the software along with the link + to the code in the `Names:` section.For E.g.:: + + class Doubler(Player): + """ + Cooperates except when the opponent has defected and + the opponent's cooperation count is less than twice their defection count. + + Names: + + - Doubler: [PRISON1998]_ + """ + Here the ``[PRISON1998]_` refers to the PRISON software. From 636c34a4338a34eef8c0b189dd4e365f74fe2989 Mon Sep 17 00:00:00 2001 From: Sourav Singh Date: Sun, 26 Feb 2017 20:59:37 +0530 Subject: [PATCH 7/9] Fix a few bugs --- docs/tutorials/contributing/strategy/docstrings.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/contributing/strategy/docstrings.rst b/docs/tutorials/contributing/strategy/docstrings.rst index a3a39c069..3af037860 100644 --- a/docs/tutorials/contributing/strategy/docstrings.rst +++ b/docs/tutorials/contributing/strategy/docstrings.rst @@ -66,4 +66,4 @@ The Sections of the docstring are: - Doubler: [PRISON1998]_ """ - Here the ``[PRISON1998]_` refers to the PRISON software. + Here the `[PRISON1998]_` refers to the PRISON software written in Java From 8288dc65015e6de5801ce4b7b3630b912e469fcf Mon Sep 17 00:00:00 2001 From: Sourav Singh Date: Mon, 27 Feb 2017 01:05:49 +0530 Subject: [PATCH 8/9] Remove entry on Software citations --- .../contributing/strategy/docstrings.rst | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/docs/tutorials/contributing/strategy/docstrings.rst b/docs/tutorials/contributing/strategy/docstrings.rst index 3af037860..741863f42 100644 --- a/docs/tutorials/contributing/strategy/docstrings.rst +++ b/docs/tutorials/contributing/strategy/docstrings.rst @@ -51,19 +51,3 @@ The Sections of the docstring are: `[Axelrod1980]_` corresponds to the bibliographic item in `docs/reference/bibliography.rst`. If you are using a source that is not in the bibliography please add it. - - If you are using a software code as a source of the startegy, - please cite the name of the software along with the link - to the code in the `Names:` section.For E.g.:: - - class Doubler(Player): - """ - Cooperates except when the opponent has defected and - the opponent's cooperation count is less than twice their defection count. - - Names: - - - Doubler: [PRISON1998]_ - """ - - Here the `[PRISON1998]_` refers to the PRISON software written in Java From 798c6123074d54d72db9f8c7f7f6f981e7c74881 Mon Sep 17 00:00:00 2001 From: Sourav Singh Date: Wed, 1 Mar 2017 21:23:08 +0530 Subject: [PATCH 9/9] Update docstrings.rst --- docs/tutorials/contributing/strategy/docstrings.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/contributing/strategy/docstrings.rst b/docs/tutorials/contributing/strategy/docstrings.rst index 741863f42..002ba3b01 100644 --- a/docs/tutorials/contributing/strategy/docstrings.rst +++ b/docs/tutorials/contributing/strategy/docstrings.rst @@ -46,7 +46,7 @@ The Sections of the docstring are: - TitForTat: [Axelrod1980]_ """ - Here,the info written under the Names section + Here, the info written under the Names section tells about the source of the TitforTat strategy. `[Axelrod1980]_` corresponds to the bibliographic item in `docs/reference/bibliography.rst`. If you are using a source