Rebuild docs

docs/API.md

@@ -1,131 +0,0 @@
-# API
-
-#### xdice.compile(pattern_string)
-
-> *Similar to `xdice.Pattern(pattern_string).compile()`*
-
-> Returns a compiled Pattern object.
-
-> Pattern object can then be rolled to obtain a PatternScore object.
-
-#### xdice.roll(pattern_string)
-
-> *Similar to `xdice.Pattern(pattern_string).roll()`*
-
-#### xdice.rolldice(faces, amount=1, drop_lowest=0, drop_highest=0)
-
-> *Similar to `xdice.Dice(faces, amount, drop_lowest, drop_highest).roll()`*
-
-## Dice object
-
-> Set of dice.
-
-#### Dice.__init__(sides, amount=1, drop_lowest=0, drop_highest=0)
-
-> Instantiate a set of dice.
-
-#### dice.roll()
-
-> Role the dice and return a Score object
-
-####*[classmethod]* Dice.parse(cls, pattern)
-
-> Parse a pattern of the form 'AdX', where A and X are positive integers, then return the corresponding Dice object.
-> Use 'AdX[Ln][Hn]' to drop the n lowest and/or highest dice when rolled.
-
-### Properties
-
-* `dice.sides`: number of sides of the dice
-* `dice.amount`: amount of dice to roll
-* `dice.drop_lowest`: amount of lowest scores to drop
-* `dice.drop_highest`: amount of highest scores to drop
-* `dice.name` : Decsriptive name of the Dice object
-
-## Score object
-
-> Score is a subclass of integer, you can then manipulate it as you would do with an integer.
-
-> It also provides an access to the detailed score with the property 'detail'.  
- 'detail' is the list of the scores obtained by each dice.
-
-> Score class can also be used as an iterable, to walk trough the individual scores.
-
-    eg:
-        >>> s = Score([1,2,3])
-        >>> print(s)
-        6
-        >>> s + 1
-        7
-        >>> list(s)
-        [1,2,3]
-
-#### Score.__new__(iterable, dropped=[], name="")
-
->*`iterable` should only contain integers*
-
-> Score value will be the sum of the list's values.
-
-#### score.format(verbose=False)
-
-> A formatted string describing the detailed result.
-
-
-### Properties
-
-* score.detail: similar to list(score), return the list of the individual results
-* score.name: descriptive name of the dice rolled
-* score.dropped: list of the dropped results
-
-
-## Pattern object
-
-> Dice notation pattern.
-
-#### Pattern.__init__(instr)
-
-> Instantiate a Pattern object.
-
-#### pattern.compile()
-
-> Parse the pattern. Two properties are updated at this time:
-
-* *pattern.format_string*
-
-> The ready-to-be-formatted string built from the `instr` argument.
-
-> *Eg: '1d6+4+1d4' => '{0}+4-{1}'*
-
- 
-* *pattern.dices*
-
-> The list of parsed dice.
-
-> *Eg: '1d6+4+1d4' => [(Dice; sides=6;amount=1), (Dice; sides=4;amount=1)]*
-
-#### pattern.roll()
-
-> Compile the pattern if it has not been yet, then roll the dice.
-
-> Return a PatternScore object.
-
-## PatternScore object
-
-> PatternScore is a subclass of **integer**, you can then manipulate it as you would do with an integer.
-
-> Moreover, you can get the list of the scores with the score(i) or scores() methods, and retrieve a formatted result with the format() method.
-
-#### pattern_score.scores()
-
-> Returns the list of Score objects extracted from the pattern and rolled.
-
-#### pattern_score.score(i)
-
-> Returns the Score object at index i.
-
-#### pattern_score.format()
-
-> Return a formatted string detailing the result of the roll.
-
-> *Eg: '3d6+4' => '[1,5,6]+4'*
-
-

docs/CLI Usage.md

@@ -1,29 +0,0 @@
-# XDice Command-Line
-
-Run `python roll.py [options] <expr>`
-	
-	Usage:
-	    roll [options] <expr>
-	
-	Options:
-	    -s               Numeric score only
-	    -v               Verbose result
-	
-	    -h --help        Displays help message
-	    --version        Displays current xdice version
-	    
-
-* Basic use
-
-	`python roll 1d6+1`
-	`>> 2       ([1]+1)`
-	
-* Numeric score only (-s)
-
-	`python roll -s 1d6+1`
-	`>> 2`
-
-* Verbose (-v)
-
-	`python roll -v 2*(3D6L1+2D4)+R3(1d4+2)`
-	`>> (2*(3d6l1(scores:[5, 6], dropped:[3])+2d4(scores:[2, 1]))+(1d4(scores:[4])+2+1d4(scores:[1])+2+1d4(scores:[4])+2))`

docs/api.rst

@@ -4,7 +4,7 @@ API
 xdice.compile(pattern\_string)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    *Similar to ``xdice.Pattern(pattern_string).compile()``*
+    Similar to `xdice.Pattern(pattern_string).compile()`
 
     Returns a compiled Pattern object.
 
@@ -13,20 +13,19 @@ xdice.compile(pattern\_string)
 xdice.roll(pattern\_string)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    *Similar to ``xdice.Pattern(pattern_string).roll()``*
+    Similar to `xdice.Pattern(pattern_string).roll()`
 
 xdice.rolldice(faces, amount=1, drop\_lowest=0, drop\_highest=0)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    *Similar to
-    ``xdice.Dice(faces, amount, drop_lowest, drop_highest).roll()``*
+    Similar to `xdice.Dice(faces, amount, drop_lowest, drop_highest).roll()`
 
 Dice object
 -----------
 
     Set of dice.
 
-Dice.\ **init**\ (sides, amount=1, drop\_lowest=0, drop\_highest=0)
+Dice.__init__ (sides, amount=1, drop\_lowest=0, drop\_highest=0)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
     Instantiate a set of dice.
@@ -43,14 +42,15 @@ dice.roll()
     integers, then return the corresponding Dice object. Use
     ‘AdX[Ln][Hn]’ to drop the n lowest and/or highest dice when rolled.
 
+
 Properties
-~~~~~~~~~~
+^^^^^^^^^^
 
--  ``dice.sides``: number of sides of the dice
--  ``dice.amount``: amount of dice to roll
--  ``dice.drop_lowest``: amount of lowest scores to drop
--  ``dice.drop_highest``: amount of highest scores to drop
--  ``dice.name`` : Decsriptive name of the Dice object
+-  `dice.sides`: number of sides of the dice
+-  `dice.amount`: amount of dice to roll
+-  `dice.drop_lowest`: amount of lowest scores to drop
+-  `dice.drop_highest`: amount of highest scores to drop
+-  `dice.name` : Descriptive name of the Dice object
 
 Score object
 ------------
@@ -76,10 +76,10 @@ Score object
         >>> list(s)
         [1,2,3]
 
-Score.\ **new**\ (iterable, dropped=\ ``_, name=“”)
+Score.__new__(iterable, dropped=[], name='')
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    *``iterable`` should only contain integers*
+    `iterable` should only contain integers
 
     Score value will be the sum of the list’s values.
 
@@ -89,7 +89,7 @@ score.format(verbose=False)
     A formatted string describing the detailed result.
 
 Properties
-~~~~~~~~~~
+^^^^^^^^^^
 
 -  score.detail: similar to list(score), return the list of the
    individual results
@@ -101,7 +101,7 @@ Pattern object
 
     Dice notation pattern.
 
-Pattern.\ **init**\ (instr)
+Pattern.__init__ (instr)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
     Instantiate a Pattern object.
@@ -145,6 +145,4 @@ pattern\_score.scores()
 ^^^^^^^^^^^^^^^^^^^^^^^
 
     Returns the list of Score objects extracted from the pattern and
-    rolled.
-
-.. _: #section
+    rolled.

docs/conf.py

@@ -40,7 +40,7 @@ templates_path = ['_templates']
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.md'
+source_suffix = '.rst'
 
 # The master toctree document.
 master_doc = 'index'

docs/dice_notation.md

@@ -1,71 +0,0 @@
-## Dice Notation
-
-*Dice notation* is nearly fully understood by pydice.
-
-### Dice
-
-> Patterns describes here can be passed to the Dice.parse() class method, and will then return the corresponding Dice object.
-
-**[See Wikipedia for a complete definition.](https://en.wikipedia.org/wiki/Dice_notation)**
-
-#### Bases
-
-Die rolls are given in the form AdX. A (amount) and X (sides) are variables, separated by the letter "d", which stands for die or dice.
-
-* A is the number of dice to be rolled (1 if omitted).
-* X is the number of faces of each die.
-
-If the final number is omitted, it is assumed to be a twenty. (This can be changed trough the class property Dice.DEFAULT_SIDES)
-
-> For example, if a game would call for a roll of d4 or 1d4 this would mean, "roll one 4-sided die."
-> `3d6` would mean, "roll three six-sided dice"
-
-Note: the `D%` notation is read as `D100`
-
-#### Selective results
-
-The `AdX` pattern can be followed by `Ln` and/or `Hn` ('L' and 'H' respectively stand for lowest and highest).
-
-In this case, the lowest/highest n scores will be discard when the dice will be rolled.
-
-*Eg: `3D6L1` will roll three 6-sided dice, and drop the lowest, while `3D6H1` will roll three 6-sided dice, and drop the highest.*
-
-Notes:
-* If no number follow the 'L' or 'H', it is assumed to be a 1.
-* 'L' and 'H' can be combined inside a single pattern.
-
-
-### Patterns
-
-> Patterns describes here can be passed to the Pattern.parse() class method.
-
-`AdX` notations can be integrated in complex expressions.
-
-Any mathematical expression is allowed:
-
-	>> 1d10+1d5+1
-	>> 1d20-6
-	>> 1d6*2
-	>> 2d20//4
-	>> 1d6*(1d4**2)
-	
-#### Builtin python functions
-
-Currently, the following python functions are allowed: `abs`, `max`, `min`
-
-#### Repeat
-
-The `Rn(AdX)` notation can be used to repat n times the `AdX` command.
-
-For example, the pattern `R3(2d6+2)` will roll `2d6+2` three times.
-
-### Examples
-
-* `1d6` 					> Roll a 6-sided die
-* `1d6+3` 				> Roll a 6-sided die, then add 3
-* `2*(1d6+3)`			> Roll a 6-sided die, add 3, then multiply by 2
-* `3d6L2`				> Roll three 6-sided dice, and drop the two lowest.
-* `R2(1d6+3)`			> Similar to `1d6+3+1d6+3`
-* `1d%`					> Similar to `1d100`
-* `d6`					> Similar to `1d6`
-* `min(1d6+10,3d6)`	> Keep the minimal score between `1d6+10` and `3d6`

docs/index.md

@@ -1,68 +0,0 @@
-# XDice
-
-## Presentation
-
-*xdice* is a lightweight python library for managing dice, scores, and dice-notation patterns.
-
-It allows to easily interpret literal expressions as rolls of dice ('1d6', '3d4+3', '12d6+1d4'...etc.), then manipulate the results.
-
-### Python Versions
-
-DiceRollParser has been tested with python 3.3+
-
-### Examples
-
-    import dice
-
-    # Roll dices with dice.rolldice()
-
-    score = dice.rolldice(6, amount=2)
-
-    # manipulate 'score' as an integer
-
-    print(score)
-    >> 11
-    print(score * 2)
-    >> 22
-    print(score == 11)
-    >> True
-
-    # Or iterate over the results
-
-    for result in score:
-        print(result)
-    >> 5
-    >> 6
-
-    # Parse patterns with dice.roll()
-
-    ps = dice.roll("2d6+18")
-
-    print(ps)
-    >> 28
-    print(ps.format())
-    >> '[5,6]+18'
-
-    ps = dice.roll("6D%L2")
-
-    print(ps)
-    >> 315
-    print(ps.format(verbose=True))
-    >> '6D%L2(scores:[80, 70, 76, 89], dropped:[2, 49])'
-
-
-### Contribution
-
-Any opinion / contribution is welcome, please contact us.
-
-### Installation
-
-	pip install xdice
-
-### License
-
-*xdice* is under GNU License
-
-### Tags
-
-	dice roll d20 game random parser dices role board

docs/index.rst

@@ -0,0 +1,12 @@
+Welcome to the documentation for xdice
+======================================
+
+Contents:
+
+.. toctree::
+    :maxdepth: 2
+
+    introduction
+    dice_notation
+    cli
+    api

docs/introduction.rst

@@ -1,83 +1,48 @@
-XDice
-=====
+Introduction
+============
+
 
 Presentation
 ------------
 
-*xdice* is a lightweight python library for managing dice, scores, and
-dice-notation patterns.
-
-It allows to easily interpret literal expressions as rolls of dice
-(‘1d6’, ‘3d4+3’, ‘12d6+1d4’…etc.), then manipulate the results.
-
-Python Versions
-~~~~~~~~~~~~~~~
+*xdice* is a dice library for Python that provides the main functionality 
+for managing dice, scores, and dice notation patterns.
 
 DiceRollParser has been tested with python 3.3+
+*xdice* is under GNU License
 
-Examples
-~~~~~~~~
+To install:
 
 ::
 
-    import dice
-
-    # Roll dices with dice.rolldice()
+    pip install xdice
 
-    score = dice.rolldice(6, amount=2)
+What can it do?
+---------------
 
-    # manipulate 'score' as an integer
+* Parse most of common dice notations: '1d6+1', 'd20', '3d%', '1d20//2 - 2*(6d6+2)', 'max(1d4+1,1d6)', '3D6L2', 'R3(1d6+1)'...etc.
+* Manipulate Dice, Pattern, and Score as objects.
+* Roll trough command-line or API
+* Understand any mathematical expression
 
-    print(score)
-    >> 11
-    print(score * 2)
-    >> 22
-    print(score == 11)
-    >> True
 
-    # Or iterate over the results
+Examples
+~~~~~~~~
 
-    for result in score:
-        print(result)
-    >> 5
-    >> 6
+::
 
-    # Parse patterns with dice.roll()
+    import dice
 
-    ps = dice.roll("2d6+18")
+    score = dice.roll("2d6+18")
 
-    print(ps)
+    print(score)
     >> 28
+    print(score*2)
+    >> 56
     print(ps.format())
     >> '[5,6]+18'
 
-    ps = dice.roll("6D%L2")
-
-    print(ps)
-    >> 315
-    print(ps.format(verbose=True))
-    >> '6D%L2(scores:[80, 70, 76, 89], dropped:[2, 49])'
-
-Contribution
-~~~~~~~~~~~~
-
-Any opinion / contribution is welcome, please contact us.
-
-Installation
-~~~~~~~~~~~~
-
-::
-
-    pip install xdice
-
-License
-~~~~~~~
-
-*xdice* is under GNU License
-
-Tags
-~~~~
-
-::
-
-    dice roll d20 game random parser dices role board
+    score = dice.roll("6D%L2")
+    
+    print(ps, ps.format(verbose=True))
+    >> 315	'6D%L2(scores:[80, 70, 76, 89], dropped:[2, 49])'