From 5e22dd89c054816ab7f6a66809d363cd7f971a65 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20Bergstr=C3=B6m?= <davbe125@student.liu.se>
Date: Thu, 2 Aug 2018 16:29:45 +0200
Subject: [PATCH] Rework documentation
---
README.md | 2 +-
docs/{playerconstants.rst => constants.rst} | 24 +++++++++-
docs/idabot.rst | 52 +++++++++++++++++++++
docs/index.rst | 24 +++-------
docs/managers.rst | 22 ++++++---
docs/quickstart.rst | 1 +
docs/types.rst | 22 +++++++++
docs/unit.rst | 5 +-
8 files changed, 122 insertions(+), 30 deletions(-)
rename docs/{playerconstants.rst => constants.rst} (53%)
create mode 100644 docs/idabot.rst
diff --git a/README.md b/README.md
index a42d5f837..05af97a64 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ Key differences:
* Everything is built using cmake, allowing for one Visual studio project to
build PyCommandCenter together with all its dependencies
-# Code example for making a bot:
+# Code example for making a bot
``` python
from library import *
diff --git a/docs/playerconstants.rst b/docs/constants.rst
similarity index 53%
rename from docs/playerconstants.rst
rename to docs/constants.rst
index 20f5d8308..d02278e14 100644
--- a/docs/playerconstants.rst
+++ b/docs/constants.rst
@@ -1,5 +1,12 @@
+Constants
+=========
+
+See also UNIT_TYPEID, UPGRADE_ID and ABILITY_ID for more constants.
+
+.. _playerconstants:
+
Player constants
-================
+----------------
The following constants are used when referring to a player:
@@ -10,3 +17,18 @@ The following constants are used when referring to a player:
These are internally represented as integers, but these constants should be
used instead to avoid confusion.
+
+Difficulty
+----------
+
+.. autoclass:: library.Difficulty
+ :members:
+ :undoc-members:
+
+Race
+----
+
+.. autoclass:: library.Race
+ :members:
+ :undoc-members:
+
diff --git a/docs/idabot.rst b/docs/idabot.rst
new file mode 100644
index 000000000..7ed0a0fb1
--- /dev/null
+++ b/docs/idabot.rst
@@ -0,0 +1,52 @@
+IDABot
+======
+
+.. class:: library.IDABot
+
+ This is the basis of your bot. It contains all available managers and some
+ methods to get you started.
+
+ See :doc:`this page <quickstart>` for how to properly
+ inherit from IDABot.
+
+ Instances of managers:
+
+ .. attribute:: IDABot.base_location_manager
+
+ An instance of the class :class:`library.BaseLocationManager`
+
+ .. attribute:: IDABot.tech_tree
+
+ An instance of the class :class:`library.TechTree`
+
+ .. attribute:: IDABot.map_tools
+
+ An instance of the class :class:`library.MapTools`
+
+ .. attribute:: IDABot.building_placer
+
+ An instance of the class :class:`library.BuildingPlacer`
+
+ Methods:
+
+ .. method:: IDABot.get_all_units(self) -> List[library.Unit]
+
+ Retrieves a list of all visible units
+
+ .. method:: IDABot.get_my_units(self) -> List[library.Unit]
+
+ Retrieves a list of all your visible units
+
+ .. method:: IDABot.get_player_race(self) -> library.Race
+
+ Returns the players race, useful if you play Race.Random
+
+ Attributes:
+
+ .. autoattribute:: minerals
+
+ .. autoattribute:: gas
+
+ .. autoattribute:: current_supply
+
+ .. autoattribute:: max_supply
diff --git a/docs/index.rst b/docs/index.rst
index d00a0c045..cdae52c67 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,17 +1,20 @@
Welcome to PyCommandCenter's documentation!
===========================================
-This is a Python module for implementing bots for Starcraft II.
+This is a Python library based on the CommandCenter bot for implementing bots for Starcraft II.
+
+.. TODO: IDABot in toctree
.. toctree::
:maxdepth: 2
:caption: Contents:
quickstart
- types
- unit
managers
- playerconstants
+ idabot
+ unit
+ types
+ constants
Short overview
==============
@@ -20,22 +23,9 @@ Short overview
:toctree: _autosummary
library
- library.ABILITY_ID
- library.BUFF_ID
- library.BaseLocation
- library.Color
library.Coordinator
- library.Difficulty
- library.IDABot
- library.PlayerSetup
library.Point2D
library.Point2DI
- library.Race
- library.TechTree
- library.TypeData
- library.UNIT_TYPEID
- library.UPGRADE_ID
- library.Unit
Indices and tables
==================
diff --git a/docs/managers.rst b/docs/managers.rst
index 73f58c515..8e34aa85c 100644
--- a/docs/managers.rst
+++ b/docs/managers.rst
@@ -1,10 +1,13 @@
Managers
========
-The original CommandCenter bot uses managers to do everything, having managers
-manage workers, building, controlling military etc. In this API we have removed
-all the control related managers and only kept the managers related to helping
-process input information, leaving the decision-making to the user of the API.
+The original `CommandCenter`_ bot uses managers to do everything, having
+managers manage workers, building, controlling military etc. In this API we
+have removed all the control related managers and only kept the managers
+related to helping process input information, leaving the decision-making to
+the user of the API.
+
+.. _CommandCenter: https://github.com/davechurchill/commandcenter
Here is a full list of all managers:
@@ -13,9 +16,7 @@ Here is a full list of all managers:
* :class:`library.MapTools`
* :class:`library.BuildingPlacer`
-The rest of this page contains the descriptions of each manager.
-
-.. TODO: How should we access the managers? Should we let the students create them themselves or should we give it to them via inhertiance
+The rest of this page contains a brief description of each manager.
BaseLocationManager
-------------------
@@ -80,6 +81,13 @@ MapTools
.. autoclass:: library.MapTools
:members:
+.. autoclass:: library.Color
+ :members:
+ :undoc-members:
+
+.. TODO: Only include the constructor and the color constants
+
+
BuildingPlacer
--------------
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index b708405ca..ff385355c 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -48,6 +48,7 @@ Now, let us break it down piece by piece to understand it.
from library import *
.. TODO: Should we really encourage this behaviour?
+
This imports everything from the library into your namespace.
Next, we need to define our bot.
diff --git a/docs/types.rst b/docs/types.rst
index 834d8b955..478ead3de 100644
--- a/docs/types.rst
+++ b/docs/types.rst
@@ -18,3 +18,25 @@ As explained above, this class is a wrapper around the class
.. autoclass:: library.UnitType
:members:
:undoc-members:
+
+UNIT_TYPEID
+-----------
+
+.. autoclass:: library.UNIT_TYPEID
+ :members:
+ :undoc-members:
+
+
+ABILITY_ID
+----------
+
+.. autoclass:: library.ABILITY_ID
+ :members:
+ :undoc-members:
+
+UPGRADE_ID
+----------
+
+.. autoclass:: library.UPGRADE_ID
+ :members:
+ :undoc-members:
diff --git a/docs/unit.rst b/docs/unit.rst
index fe37a6d56..0ffe399fc 100644
--- a/docs/unit.rst
+++ b/docs/unit.rst
@@ -37,11 +37,8 @@ Unit
.. autoattribute:: is_valid
.. attribute:: Unit.player
- .. TODO: Add page about PLAYER_* constants
-
Returns the constant corresponding to player which this unit belongs to.
- See the page :doc:`playerconstants` for more information on player
- constants.
+ See :ref:`playerconstants` for more information.
.. autoattribute:: position
.. autoattribute:: shields
--
GitLab