diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 5b495dda..2f144a10 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -192,10 +192,9 @@ def setup(app): #latex_domain_indices = True """ # extlinks alias -extlinks = {'issue': ('https://github.com/NREL/bifacial_radiance/issues/%s', - 'GH'), - 'wiki': ('https://github.com/NREL/bifacial_radiance/wiki/%s', - 'wiki '), +extlinks = {'issue': ('https://github.com/NREL/bifacial_radiance/issues/%s', 'GH'), + 'pull': ('https://github.com/NREL/bifacial_radiance/pull/%s', 'GH'), + 'wiki': ('https://github.com/NREL/bifacial_radiance/wiki/%s', 'wiki '), 'doi': ('http://dx.doi.org/%s', 'DOI: '), 'ghuser': ('https://github.com/%s', '@')} """ diff --git a/docs/sphinx/source/contributing.rst b/docs/sphinx/source/contributing.rst index 6c27575b..5137d6fa 100644 --- a/docs/sphinx/source/contributing.rst +++ b/docs/sphinx/source/contributing.rst @@ -199,9 +199,9 @@ style. Remove any ``logging`` calls and ``print`` statements that you added during development. ``warning`` is ok. - + We typically use GitHub's -"`squash and merge` _" +"`squash and merge `_" feature to merge your pull request into bifacial_radiance. GitHub will condense the commit history of your branch into a single commit when merging into bifacial_radiance/master (the commit history on your branch remains @@ -231,17 +231,30 @@ specific types may be used: Parameters that specify a specific type require that specific input type. -A relatively easy way to test your documentation is to build it on -`readthedocs.org ` by following their -`Import Your Docs `_ -instructions and enabling your branch on the readthedocs -`versions admin page `_. +Read the Docs will automatically build the documentation for each pull +request. Please confirm the documentation renders correctly by following +the ``continuous-documentation/read-the-docs`` link within the checks +status box at the bottom of the pull request. + +To build the docs locally, install the ``doc`` dependencies specified in the +`setup.py `_ +file. See :ref:`installation` instructions for more information. .. _testing: Testing ~~~~~~~ +Developers **must** include comprehensive tests for any additions or +modifications to bifacial_radiance. New unit test code should be placed in the corresponding test module in the bifacial_radiance/test directory. + +A pull request will automatically run the tests for you on Linux platform and python versions 2.7 and 3.6. However, it is typically more efficient to run and debug the tests in your own local +environment. + +To run the tests locally, install the ``test`` dependencies specified in the +`setup.py `_ +file. See :ref:`installation` instructions for more information.i + bifacial_radiance's unit tests can easily be run by executing ``pytest`` on the bifacial_radiance directory: @@ -257,7 +270,7 @@ or, for a single test: We suggest using pytest's ``--pdb`` flag to debug test failures rather than using ``print`` or ``logging`` calls. For example: - + ``pytest bifacial_radiance/test/modelchain.py --pdb`` will drop you into the @@ -266,12 +279,6 @@ location of a test failure. As described in :ref:`code-style`, bifacial_radiance code does not use ``print`` or ``logging`` calls, and this also applies to the test suite (with rare exceptions). -New unit test code should be placed in the corresponding test module in -the bifacial_radiance/test directory. - -Developers **must** include comprehensive tests for any additions or -modifications to bifacial_radiance. - This documentation ~~~~~~~~~~~~~~~~~~