Contributing to Dungeonsheets¶

Thanks for taking the time to contribute to dungeonsheets!

Dungeonsheets is a small project and relies on volunteers like to you to continue pushing new features and improvements. Issues and pull-requests are welcomed and encouraged. This document is meant to provide guidelines that clarify how you can best help; nothing is written in stone.

Scope¶

Dungeonsheets is intended as a tool for creating character sheets and game-maker (GM/DM) sheets. A secondary goal is to provide high-level classes that are suitable for incorporation to other projects.

Please ensure that all contributions are within the scope of dungeonsheets, or if not, are accompanied by a compelling argument for why the scope should be expanded. If your project requires changes to a core class (e.g. Character), these will be considered, especially if the change will be broadly applicable to the usability of that class.

What to Contribute¶

Before submitting pull requests, please check the following:

All tests in tests/ pass.
All example character sheets in the examples/ directory build properly, both with and without the --fancy option.
The submission passes linting by flake8 (optional).
The submission is formatted by black (optional).

Adding Features¶

Submissions for new features are welcome, provided they are within the scope of dungeonsheets. If the submission adds parameters to the character.py schema, please ensure the following:

At least one example sheet (in examples/) should include the new parameters, either by adding a new example or modifying an existing example.
Older character.py sheets should still build properly without the parameter.
Documentation in docs/ is consistent with the new parameter.

Adding Content¶

Submissions with new game content (e.g. monsters, spells, features) are welcome. The mechanics of the content should be included as a subclass of the relevant mechanic (e.g. Monster, Spell, Feature). The values themselves will be attributes of this subclass. The description of the content should form the docstring of the subclass. This docstring will be rendered into the final character sheet, spellbook, etc. Therefore, is should be properly formed reStructuredText. Also, the docstring should be free of extra content.

Please respect intellectual property rights before submitting new content. If you did not write the content that is being submitted, check the relevant licensing to ensure there are no copyright or other IP violations.

How to Contribute¶

Running Tests¶

Dungeonsheets uses tests to verify the package works as intended. Tests are found in the tests/ folder. To run the tests using pytest, run the following from a console:

pip install -r requirements.txt -r requirements-tests.txt
pytest

You can also run a sub-set of the tests, which can be convenient for development. For example, to run just the tests related to dice mechanics, use pytest tests/test_dice.py. Dungeonsheets defines tests using the unittest package in the standard library. For example, to test a new function in the dungeonsheets/dice.py module, modify tests/test_dice.py:

dice.py¶

def roll(a, b=None):
    """roll(20) means roll 1d20, roll(2, 6) means roll 2d6"""
    if b is None:
        return random.randint(1, a)
    else:
        return sum([random.randint(1, b) for _ in range(a)])

test_dice.py¶

 from unittest import TestCase
 from dungeonsheets.dice import roll

 class TestDice(TestCase):
     def test_simple_rolling(self):
         num_tests = 100
         # Do a bunch of rolls and make sure the numbers are within the requsted range
         for _ in range(num_tests):
             result = roll(6)
             self.assertGreaterEqual(result, 1)
             self.assertLessEqual(result, 6)

     def test_multi_rolling(self):
         num_tests = 100
         for _ in range(num_tests):
             result = roll(2, 4)  # Roll 2d4
             self.assertGreaterEqual(result, 2)
             self.assertLessEqual(result, 8)

Building Documentation¶

Dungeonsheets uses sphinx to build documentations. All files are in reStructuredText and are kept in the docs/ folder. To build the HTML files, run:

pip install -r requirements.txt -r requirements-tests.txt
cd docs/
make html

The results can be found in the _build/html/ foler.

Submitting Bugs¶

First, please check the list of open issues to make sure your bug has no already been reported. If your bug has not been previously reported, consider submitting a new issue.

Submitting Pull Requests¶

Pull requests are welcome, both for bug fixes and new features. At a minimum, pull requests should not break existing tests.