Move documentation to diataxis (#1391)

* Delete an old file. * Display version number in docs. * Move tutorials to tutorial structure. * Move research topic tutorials to how to guides. * Move advanced to how to guides. * Add citation to how to guides. * Remove certain things from the reference section. * Move files to discussion section. * Add community and contribution guidelines back. * Move contributing and community guides. * Fix some remaining tutorials. * Remove duplicate entry.
Axelrod-Python · Jun 4, 2021 · 75ef1f2 · 75ef1f2
1 parent 6af4bdb
commit 75ef1f2
Show file tree

Hide file tree

Showing 83 changed files with 103 additions and 694 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -82,9 +82,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = "0.0"
+version = axelrod.__version__
 # The full version, including alpha/beta/rc tags.
-release = "0.0.1"
+release = axelrod.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/docs/reference/description.rst → docs/discussion/axelrods_tournaments.rst b/docs/reference/description.rst → docs/discussion/axelrods_tournaments.rst
diff --git a/docs/community/coc.rst → docs/discussion/community/coc.rst b/docs/community/coc.rst → docs/discussion/community/coc.rst
diff --git a/docs/community/communication.rst → docs/discussion/community/communication.rst b/docs/community/communication.rst → docs/discussion/community/communication.rst
diff --git a/docs/community/index.rst → docs/discussion/community/index.rst b/docs/community/index.rst → docs/discussion/community/index.rst
diff --git a/docs/community/team.rst → docs/discussion/community/team.rst b/docs/community/team.rst → docs/discussion/community/team.rst
diff --git a/docs/reference/fortan_keys.rst → docs/discussion/fortan_keys.rst b/docs/reference/fortan_keys.rst → docs/discussion/fortan_keys.rst
diff --git a/docs/discussion/index.rst b/docs/discussion/index.rst
@@ -0,0 +1,16 @@
+Discussion
+==========
+
+This section is a discussion of various aspects of Game Theory related to the
+Axelrod library.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   axelrods_tournaments.rst
+   strategy_archetypes.rst
+   overview_of_past_tournaments.rst
+   play_contexts.rst
+   community/index.rst
diff --git a/docs/reference/overview_of_strategies.rst → ...scussion/overview_of_past_tournaments.rst b/docs/reference/overview_of_strategies.rst → ...scussion/overview_of_past_tournaments.rst
@@ -1,5 +1,5 @@
-Tournaments
-===========
+Overview of past Tournaments
+============================
 
 Axelrod's first tournament
 --------------------------

diff --git a/docs/reference/play_contexts.rst → docs/discussion/play_contexts.rst b/docs/reference/play_contexts.rst → docs/discussion/play_contexts.rst
diff --git a/...orials/further_topics/meta_strategies.rst → docs/discussion/strategy_archetypes.rst b/...orials/further_topics/meta_strategies.rst → docs/discussion/strategy_archetypes.rst
@@ -1,7 +1,7 @@
 .. _metastrategies:
 
-Meta-Strategies
-===============
+Strategy Archetypes
+===================
 
 Finite State Machines
 ---------------------

diff --git a/...cal_variant/demo_strategies_stackplot.svg → ...cal_variant/demo_strategies_stackplot.svg b/...cal_variant/demo_strategies_stackplot.svg → ...cal_variant/demo_strategies_stackplot.svg
diff --git a/...ics/_static/fingerprinting/WSLS_large.png → ...-to/_static/fingerprinting/WSLS_large.png b/...ics/_static/fingerprinting/WSLS_large.png → ...-to/_static/fingerprinting/WSLS_large.png
diff --git a/..._static/fingerprinting/WSLS_large_alt.png → ..._static/fingerprinting/WSLS_large_alt.png b/..._static/fingerprinting/WSLS_large_alt.png → ..._static/fingerprinting/WSLS_large_alt.png
diff --git a/...ics/_static/fingerprinting/WSLS_small.png → ...-to/_static/fingerprinting/WSLS_small.png b/...ics/_static/fingerprinting/WSLS_small.png → ...-to/_static/fingerprinting/WSLS_small.png
diff --git a/..._static/fingerprinting/transitive_TFT.png → ..._static/fingerprinting/transitive_TFT.png b/..._static/fingerprinting/transitive_TFT.png → ..._static/fingerprinting/transitive_TFT.png
diff --git a/...rprinting/transitive_TFT_against_demo.png → ...rprinting/transitive_TFT_against_demo.png b/...rprinting/transitive_TFT_against_demo.png → ...rprinting/transitive_TFT_against_demo.png
diff --git a/...naments/demo_strategies_noisy_boxplot.svg → ...naments/demo_strategies_noisy_boxplot.svg b/...naments/demo_strategies_noisy_boxplot.svg → ...naments/demo_strategies_noisy_boxplot.svg
diff --git a/...naments/demo_strategies_noisy_winplot.svg → ...naments/demo_strategies_noisy_winplot.svg b/...naments/demo_strategies_noisy_winplot.svg → ...naments/demo_strategies_noisy_winplot.svg
diff --git a/...prob_end_tournaments/prob_end_boxplot.svg → ...prob_end_tournaments/prob_end_boxplot.svg b/...prob_end_tournaments/prob_end_boxplot.svg → ...prob_end_tournaments/prob_end_boxplot.svg
diff --git a/...b_end_tournaments/prob_end_lengthplot.svg → ...b_end_tournaments/prob_end_lengthplot.svg b/...b_end_tournaments/prob_end_lengthplot.svg → ...b_end_tournaments/prob_end_lengthplot.svg
diff --git a/...s/_static/spatial_tournaments/spatial.png → ...o/_static/spatial_tournaments/spatial.png b/...s/_static/spatial_tournaments/spatial.png → ...o/_static/spatial_tournaments/spatial.png
diff --git a/...c/spatial_tournaments/spatial_results.png → ...c/spatial_tournaments/spatial_results.png b/...c/spatial_tournaments/spatial_results.png → ...c/spatial_tournaments/spatial_results.png
diff --git a/docs/tutorials/advanced/strategies.rst → ...w-to/access_collections_of_strategies.rst b/docs/tutorials/advanced/strategies.rst → ...w-to/access_collections_of_strategies.rst
@@ -1,7 +1,7 @@
 .. _strategies:
 
-Accessing strategies
-====================
+Access collections of strategies
+================================
 
 All of the strategies are accessible from the main name space of the library.
 For example::

diff --git a/...tutorials/advanced/tournament_results.rst → docs/how-to/access_tournament_results.rst b/...tutorials/advanced/tournament_results.rst → docs/how-to/access_tournament_results.rst
@@ -1,7 +1,7 @@
 .. _tournament-results:
 
-Accessing tournament results
-============================
+Access tournament results
+=========================
 
 This tutorial will show you how to access the various results of a tournament:
 

diff --git a/...rials/further_topics/morality_metrics.rst → docs/how-to/calculate_morality_metrics.rst b/...rials/further_topics/morality_metrics.rst → docs/how-to/calculate_morality_metrics.rst
@@ -1,7 +1,7 @@
 .. _morality-metrics:
 
-Morality Metrics
-================
+Calculate Morality Metrics
+==========================
 
 Tyler Singer-Clark's June 2014 paper, "Morality Metrics On Iterated Prisoner’s
 Dilemma Players" [Singer-Clark2014]_), describes several interesting metrics which

diff --git a/docs/tutorials/advanced/player_equality.rst → docs/how-to/check_player_equality.rst b/docs/tutorials/advanced/player_equality.rst → docs/how-to/check_player_equality.rst
@@ -1,5 +1,5 @@
-Player equality
-===============
+Check Player equality
+=====================
 
 It is possible to test for player equality using :code:`==`::
 

diff --git a/docs/citing_the_library.rst → docs/how-to/cite_the_library.rst b/docs/citing_the_library.rst → docs/how-to/cite_the_library.rst
@@ -1,5 +1,5 @@
-Citing the library
-==================
+Cite the library
+================
 
 We would be delighted if anyone wanted to use and/or reference this library for
 their own research.

diff --git a/...advanced/classification_of_strategies.rst → docs/how-to/classify_strategies.rst b/...advanced/classification_of_strategies.rst → docs/how-to/classify_strategies.rst
diff --git a/docs/tutorials/contributing/guidelines.rst → docs/how-to/contributing/guidelines.rst b/docs/tutorials/contributing/guidelines.rst → docs/how-to/contributing/guidelines.rst
diff --git a/docs/tutorials/contributing/index.rst → docs/how-to/contributing/index.rst b/docs/tutorials/contributing/index.rst → docs/how-to/contributing/index.rst
@@ -1,5 +1,5 @@
-Contributing
-============
+Contribute
+==========
 
 This section contains a variety of tutorials that should help you contribute to
 the library.

diff --git a/.../tutorials/contributing/library/index.rst → docs/how-to/contributing/library/index.rst b/.../tutorials/contributing/library/index.rst → docs/how-to/contributing/library/index.rst
diff --git a/.../tutorials/contributing/running_tests.rst → docs/how-to/contributing/running_tests.rst b/.../tutorials/contributing/running_tests.rst → docs/how-to/contributing/running_tests.rst
diff --git a/...ntributing/setting_up_the_environment.rst → ...ntributing/setting_up_the_environment.rst b/...ntributing/setting_up_the_environment.rst → ...ntributing/setting_up_the_environment.rst
diff --git a/...ting/strategy/adding_the_new_strategy.rst → ...ting/strategy/adding_the_new_strategy.rst b/...ting/strategy/adding_the_new_strategy.rst → ...ting/strategy/adding_the_new_strategy.rst
diff --git a/...strategy/classifying_the_new_strategy.rst → ...strategy/classifying_the_new_strategy.rst b/...strategy/classifying_the_new_strategy.rst → ...strategy/classifying_the_new_strategy.rst
diff --git a/...ials/contributing/strategy/docstrings.rst → ...w-to/contributing/strategy/docstrings.rst b/...ials/contributing/strategy/docstrings.rst → ...w-to/contributing/strategy/docstrings.rst
diff --git a/...tutorials/contributing/strategy/index.rst → docs/how-to/contributing/strategy/index.rst b/...tutorials/contributing/strategy/index.rst → docs/how-to/contributing/strategy/index.rst
diff --git a/...ls/contributing/strategy/instructions.rst → ...to/contributing/strategy/instructions.rst b/...ls/contributing/strategy/instructions.rst → ...to/contributing/strategy/instructions.rst
diff --git a/...egy/writing_test_for_the_new_strategy.rst → ...egy/writing_test_for_the_new_strategy.rst b/...egy/writing_test_for_the_new_strategy.rst → ...egy/writing_test_for_the_new_strategy.rst
diff --git a/...ing/strategy/writing_the_new_strategy.rst → ...ing/strategy/writing_the_new_strategy.rst b/...ing/strategy/writing_the_new_strategy.rst → ...ing/strategy/writing_the_new_strategy.rst
diff --git a/...er_topics/approximate_moran_processes.rst → ...to/create_approximate_moran_processes.rst b/...er_topics/approximate_moran_processes.rst → ...to/create_approximate_moran_processes.rst
@@ -1,7 +1,7 @@
 .. _approximate-moran-process:
 
-Approximate Moran Process
-=========================
+Create Approximate Moran Process
+================================
 
 Due to the high computational cost of a single Moran process, an approximate
 Moran process is implemented that can make use of cached outcomes of games. The

diff --git a/...ther_topics/moran_processes_on_graphs.rst → ...w-to/create_moran_processes_on_graphs.rst b/...ther_topics/moran_processes_on_graphs.rst → ...w-to/create_moran_processes_on_graphs.rst
@@ -1,7 +1,7 @@
 .. _moran-process-on-graphs:
 
-Moran Process on Graphs
-=======================
+Create Moran Processes On Graphs
+================================
 
 The library also provides a graph-based Moran process [Shakarian2013]_ with
 :code:`MoranProcess`.  To use this feature you must supply at least one

diff --git a/...ls/further_topics/spatial_tournaments.rst → docs/how-to/create_spatial_tournaments.rst b/...ls/further_topics/spatial_tournaments.rst → docs/how-to/create_spatial_tournaments.rst
@@ -1,5 +1,5 @@
-Spatial tournaments
-===================
+Create spatial tournaments
+==========================
 
 A spatial tournament is defined on a graph where the nodes correspond to players
 and edges define whether or not a given player pair will have a match.

diff --git a/...ials/further_topics/evolvable_players.rst → docs/how-to/evolve_players.rst b/...ials/further_topics/evolvable_players.rst → docs/how-to/evolve_players.rst
@@ -1,7 +1,7 @@
 .. _evolvable_players:
 
-Evolvable Players
-=================
+Evolve Players
+==============
 
 Several strategies in the library derive from :code:`EvolvablePlayer` which specifies methods
 allowing evolutionary or particle swarm algorithms to be used with these strategies. The

diff --git a/...torials/further_topics/fingerprinting.rst → docs/how-to/fingerprint.rst b/...torials/further_topics/fingerprinting.rst → docs/how-to/fingerprint.rst
@@ -1,7 +1,7 @@
 .. _fingerprinting:
 
-Fingerprinting
-==============
+Fingerprint
+===========
 
 Ashlock Fingerprints
 --------------------

diff --git a/...ials/further_topics/noisy_tournaments.rst → docs/how-to/include_noise.rst b/...ials/further_topics/noisy_tournaments.rst → docs/how-to/include_noise.rst
@@ -1,5 +1,5 @@
-Noisy tournaments
-=================
+Include noise
+=============
 
 A common variation on iterated prisoner’s dilemma tournaments is to add
 stochasticity in the choice of actions, simply called noise. This noise is

diff --git a/...topics/probabilistict_end_tournaments.rst → .../how-to/include_probabilistic_endings.rst b/...topics/probabilistict_end_tournaments.rst → .../how-to/include_probabilistic_endings.rst
@@ -1,5 +1,5 @@
-Probabilistic Ending Tournaments
-================================
+Include probabilistic endings
+=============================
 
 It is possible to create a tournament where the length of each Match is not
 constant for all encounters: after each turn the Match ends with a given

diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst
@@ -0,0 +1,31 @@
+How to
+======
+
+This section contains short descriptions of how to accomplish specific tasks
+with the Axelrod library.
+
+.. toctree::
+   :maxdepth: 1
+
+   include_noise.rst
+   include_probabilistic_endings.rst
+   create_spatial_tournaments.rst
+   create_moran_processes_on_graphs.rst
+   create_approximate_moran_processes.rst
+   calculate_morality_metrics.rst
+   run_axelrods_ecological_variant.rst
+   fingerprint.rst
+   evolve_players.rst
+   access_collections_of_strategies.rst
+   classify_strategies.rst
+   use_strategy_transformers.rst
+   access_tournament_results.rst
+   read_and_write_interactions.rst
+   use_parallel_processing.rst
+   use_a_cache.rst
+   use_different_stage_games.rst
+   set_a_seed.rst
+   set_player_information.rst
+   check_player_equality.rst
+   cite_the_library.rst
+   contributing/index.rst
diff --git a/...nced/reading_and_writing_interactions.rst → docs/how-to/read_and_write_interactions.rst b/...nced/reading_and_writing_interactions.rst → docs/how-to/read_and_write_interactions.rst
@@ -1,5 +1,5 @@
-Reading and writing interactions from/to file
-=============================================
+Read and write interactions from/to file
+========================================
 
 When dealing with large tournaments it might be desirable to separate the
 analysis from the actual running of the tournaments. This can be done by passing

diff --git a/...als/further_topics/ecological_variant.rst → ...ow-to/run_axelrods_ecological_variant.rst b/...als/further_topics/ecological_variant.rst → ...ow-to/run_axelrods_ecological_variant.rst
@@ -1,7 +1,7 @@
 .. _ecological-variant:
 
-Ecological Variant
-==================
+Run Axelrod's Ecological Variant
+================================
 
 In Axelrod's original work an ecological approach based on the payoff matrix of
 the tournament was used to study the evolutionary stability of each strategy.

diff --git a/docs/tutorials/advanced/setting_a_seed.rst → docs/how-to/set_a_seed.rst b/docs/tutorials/advanced/setting_a_seed.rst → docs/how-to/set_a_seed.rst
@@ -1,7 +1,7 @@
 .. _setting_a_seed:
 
-Setting a random seed
-=====================
+Set a random seed
+==================
 
 The library has a variety of strategies whose behaviour is stochastic. To ensure
 reproducible results a random seed should be set. The library abstracts away the

diff --git a/...tutorials/advanced/player_information.rst → docs/how-to/set_player_information.rst b/...tutorials/advanced/player_information.rst → docs/how-to/set_player_information.rst
@@ -1,7 +1,7 @@
 .. _player_information:
 
-Player information
-==================
+Set Player information
+======================
 
 It is possible to determine what information players know about their matches.
 By default all known information is given.  For example let us create a match

diff --git a/docs/tutorials/advanced/using_the_cache.rst → docs/how-to/use_a_cache.rst b/docs/tutorials/advanced/using_the_cache.rst → docs/how-to/use_a_cache.rst
@@ -1,7 +1,7 @@
 .. _using-the-cache:
 
-Using the cache
-===============
+Use a cache
+===========
 
 Whilst for stochastic strategies, every repetition of a Match will give a
 different result, for deterministic strategies, when there is no noise there is

diff --git a/docs/tutorials/advanced/games.rst → docs/how-to/use_different_stage_games.rst b/docs/tutorials/advanced/games.rst → docs/how-to/use_different_stage_games.rst
@@ -1,5 +1,5 @@
-Using and playing different stage games
-=======================================
+Use different stage games
+=========================
 
 As described in :ref:`play_contexts` the default game used for the Prisoner's
 Dilemma is given by::

diff --git a/...utorials/advanced/parallel_processing.rst → docs/how-to/use_parallel_processing.rst b/...utorials/advanced/parallel_processing.rst → docs/how-to/use_parallel_processing.rst
@@ -1,5 +1,5 @@
-Parallel processing
-===================
+Use Parallel processing
+=======================
 
 When dealing with large tournaments on a multi core machine it is possible to
 run the tournament in parallel **although this is not currently supported on

diff --git a/...orials/advanced/strategy_transformers.rst → docs/how-to/use_strategy_transformers.rst b/...orials/advanced/strategy_transformers.rst → docs/how-to/use_strategy_transformers.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -97,12 +97,12 @@ Table of Contents
 -----------------
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 1
 
    tutorials/index.rst
+   how-to/index.rst
+   discussion/index.rst
    reference/index.rst
-   community/index.rst
-   citing_the_library.rst
 
 
 Indices and tables

diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -3,14 +3,9 @@ Reference
 
 This section is the reference guide for the various components of the library.
 
-Contents:
-
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   description.rst
-   play_contexts.rst
-   overview_of_strategies.rst
-   all_strategies.rst
    bibliography.rst
+   strategy_index.rst
    glossary.rst
diff --git a/docs/reference/all_strategies.rst → docs/reference/strategy_index.rst b/docs/reference/all_strategies.rst → docs/reference/strategy_index.rst
@@ -1,7 +1,7 @@
 .. _strategies-index:
 
-Strategies index
-================
+Strategy index
+==============
 
 Here are the docstrings of all the strategies in the library.
 

diff --git a/docs/tutorials/advanced/index.rst b/docs/tutorials/advanced/index.rst
diff --git a/docs/tutorials/further_topics/index.rst b/docs/tutorials/further_topics/index.rst