From e43dbc5debcfa010c832a7729dd9431c9ad07117 Mon Sep 17 00:00:00 2001 From: olinox Date: Sun, 24 Sep 2017 22:20:52 +0200 Subject: [PATCH] Rebuild docs --- docs/API.md | 131 ------------------------------------------ docs/CLI Usage.md | 29 ---------- docs/api.rst | 34 ++++++----- docs/conf.py | 2 +- docs/dice_notation.md | 71 ----------------------- docs/index.md | 68 ---------------------- docs/index.rst | 12 ++++ docs/introduction.rst | 87 +++++++++------------------- 8 files changed, 55 insertions(+), 379 deletions(-) delete mode 100644 docs/API.md delete mode 100644 docs/CLI Usage.md delete mode 100644 docs/dice_notation.md delete mode 100644 docs/index.md create mode 100644 docs/index.rst diff --git a/docs/API.md b/docs/API.md deleted file mode 100644 index ba7a49d..0000000 --- a/docs/API.md +++ /dev/null @@ -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'* - - diff --git a/docs/CLI Usage.md b/docs/CLI Usage.md deleted file mode 100644 index 69369d3..0000000 --- a/docs/CLI Usage.md +++ /dev/null @@ -1,29 +0,0 @@ -# XDice Command-Line - -Run `python roll.py [options] ` - - Usage: - roll [options] - - 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))` \ No newline at end of file diff --git a/docs/api.rst b/docs/api.rst index a286de1..f25b69f 100644 --- a/docs/api.rst +++ b/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 \ No newline at end of file + rolled. \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index aa8fac8..85c2544 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -40,7 +40,7 @@ # 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' diff --git a/docs/dice_notation.md b/docs/dice_notation.md deleted file mode 100644 index ae4c2d3..0000000 --- a/docs/dice_notation.md +++ /dev/null @@ -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` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 7fcceb9..0000000 --- a/docs/index.md +++ /dev/null @@ -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 \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..be69457 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,12 @@ +Welcome to the documentation for xdice +====================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + introduction + dice_notation + cli + api \ No newline at end of file diff --git a/docs/introduction.rst b/docs/introduction.rst index a12cffd..4556eee 100644 --- a/docs/introduction.rst +++ b/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 \ No newline at end of file + score = dice.roll("6D%L2") + + print(ps, ps.format(verbose=True)) + >> 315 '6D%L2(scores:[80, 70, 76, 89], dropped:[2, 49])'