Tidying up namespaces (#220)

* Tidying up public API, moving towards stabilisation

* Remove unused variables

* Expanding docs: add reference section

* Add significant docs

* Add further docs to reference section

docs/source/conf.py

@@ -10,9 +10,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../..'))
 
 
 # -- Project information -----------------------------------------------------
@@ -31,7 +31,9 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autosectionlabel',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.napoleon",
 ]
 
 autosectionlabel_prefix_document = True

docs/source/guide/pyproject.toml.rst

@@ -1,7 +1,7 @@
 .. _pyproject:
 
-Configuring Ward in ``pyproject.toml``
-========================================
+Configuration
+=============
 
 How does Ward use ``pyproject.toml``?
 -------------------------------------
@@ -39,4 +39,5 @@ all of your Ward configuration should appear there:
     order = "standard"  # or 'random'
     output-mode = "test-per-line"  # or 'dots-global', 'dot-module'
     fail-limit = 20  # stop the run if 20 fails occur
-    search = "my_function"  # search in test body or description
+    search = "my_function"  # search in test body or description
+    progress-style = ["bar"]  # display a progress bar during the run

docs/source/index.rst

@@ -13,7 +13,7 @@ Features
 * Support for :ref:`testing async code<async_tests>`
 * :ref:`Parameterised testing <parameterisation>` allows you to run a single test on multiple inputs
 * Configurable with :ref:`pyproject.toml<pyproject>`, but works out-of-the-box with sensible defaults
-* Fast -- Ward's suite of ~250 tests completes in <0.3 seconds on my machine
+* Speedy -- Ward's suite of ~300 tests completes in ~0.4 seconds on my machine
 
 .. image:: ./_static/intro_screenshot.png
     :align: center
@@ -57,4 +57,13 @@ To run the test, simply run ``ward`` in your terminal, and Ward will let you kno
     :caption: Tutorials
 
     tutorials/first_tests.rst
-    tutorials/testing_flask.rst
+    tutorials/testing_flask.rst
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Reference
+    :glob:
+
+    reference/testing.rst
+    reference/fixtures.rst
+

docs/source/reference/fixtures.rst

@@ -0,0 +1,18 @@
+``ward.fixtures``
+===================
+
+Standard API
+-------------
+
+.. automodule:: ward.fixtures
+    :members: fixture, using
+
+Plugin API (in development)
+----------------------------
+This section contains items from this module that are intended for use by plugin authors or those contributing to Ward itself.
+If you're just using Ward to write your tests, this section isn't relevant.
+
+.. automodule:: ward.fixtures
+    :noindex:
+    :members: Fixture
+

docs/source/reference/testing.rst

@@ -0,0 +1,18 @@
+``ward.testing``
+===================
+
+Standard API
+-------------
+
+.. automodule:: ward.testing
+    :members: test, skip, xfail
+
+Plugin API (in development)
+----------------------------
+This section contains items from this module that are intended for use by plugin authors or those contributing to Ward itself.
+If you're just using Ward to write your tests, this section isn't relevant.
+
+.. automodule:: ward.testing
+    :noindex:
+    :members: Test, TestOutcome, TestResult
+

pyproject.toml

@@ -56,7 +56,7 @@ Sphinx = "^3.5.1"
 sphinx-rtd-theme = "^0.5.1"
 
 [tool.poetry.scripts]
-ward = "ward.run:run"
+ward = "ward._run:run"
 
 [tool.coverage.report]
 exclude_lines = [

tests/test_cli.py

@@ -1,7 +1,7 @@
 from click.testing import CliRunner
 
 from ward import each, test
-from ward.run import run
+from ward._run import run
 
 
 @test("Cannot use bar progress style with {output_style} output style")

tests/test_collect.py

@@ -9,7 +9,7 @@
 from cucumber_tag_expressions import parse
 
 from ward import fixture, raises, test
-from ward.collect import (
+from ward._collect import (
     _get_module_path,
     _handled_within,
     _is_excluded_module,

tests/test_config.py

@@ -4,7 +4,7 @@
 import click
 
 from ward import test, fixture, raises, each
-from ward.config import read_config_toml, as_list, apply_multi_defaults
+from ward._config import read_config_toml, as_list, apply_multi_defaults
 
 
 def temp_conf(conf: str) -> tempfile._TemporaryFileWrapper:

tests/test_debug.py

@@ -5,8 +5,8 @@
 from unittest import mock
 from unittest.mock import Mock
 
-from ward import test, debug
-from ward.debug import init_breakpointhooks, _breakpointhook, _get_debugger_hook, importlib
+from ward import test, _debug
+from ward._debug import init_breakpointhooks, _breakpointhook, _get_debugger_hook, importlib
 
 
 @test("init_breakpointhooks always patches pdb.set_trace")
@@ -18,21 +18,21 @@ def _():
 
 @test("init_breakpointhooks sets sys.breakpointhook when it's supported")
 def _():
-    old_func = debug._breakpoint_supported
-    debug._breakpoint_supported = lambda: True
+    old_func = _debug._breakpoint_supported
+    _debug._breakpoint_supported = lambda: True
     mock_sys = SimpleNamespace()
     init_breakpointhooks(pdb_module=Mock(), sys_module=mock_sys)
-    debug._breakpoint_supported = old_func
+    _debug._breakpoint_supported = old_func
     assert mock_sys.breakpointhook == _breakpointhook
 
 
 @test("init_breakpointhooks doesnt set breakpointhook when it's unsupported")
 def _():
-    old_func = debug._breakpoint_supported
-    debug._breakpoint_supported = lambda: False
+    old_func = _debug._breakpoint_supported
+    _debug._breakpoint_supported = lambda: False
     mock_sys = SimpleNamespace()
     init_breakpointhooks(pdb_module=Mock(), sys_module=mock_sys)
-    debug._breakpoint_supported = old_func
+    _debug._breakpoint_supported = old_func
     assert not hasattr(mock_sys, "breakpointhook")
 
 

tests/test_fixtures.py

@@ -2,14 +2,12 @@
 import sys
 
 from tests.utilities import testable_test
-from ward.fixtures import (
-    is_fixture,
-    fixture_parents_and_children,
-)
-from ward import fixture, test, Scope, raises, each
-from ward.fixtures import Fixture, FixtureCache, using
+from ward import fixture, test, raises, each
+from ward.models import Scope
+from ward.fixtures import Fixture, using
+from ward._fixtures import FixtureCache, is_fixture, fixture_parents_and_children
 from ward.testing import Test
-from ward.errors import FixtureError
+from ward._errors import FixtureError
 from tests.utilities import dummy_fixture
 
 

tests/test_models.py

@@ -1,7 +1,7 @@
 from tests.test_testing import TRUTHY_PREDICATES, FALSY_PREDICATES
-from ward import test, each, Scope, raises
-from ward.errors import FixtureError
-from ward.models import SkipMarker, XfailMarker
+from ward import test, each, raises
+from ward._errors import FixtureError
+from ward.models import SkipMarker, XfailMarker, Scope
 
 
 @test("Scope.from_str('{string}') returns {scope}")

tests/test_rewrite.py

@@ -2,7 +2,7 @@
 
 from tests.utilities import testable_test
 from ward import test, fixture
-from ward.rewrite import (
+from ward._rewrite import (
     rewrite_assertions_in_tests,
     RewriteAssert,
     get_assertion_msg,

tests/test_suite.py

@@ -1,9 +1,9 @@
 from unittest import mock
 
 from ward import fixture
-from ward.errors import ParameterisationError
+from ward._errors import ParameterisationError
 from ward.models import Scope, SkipMarker
-from ward.suite import Suite
+from ward._suite import Suite
 from ward.testing import Test, skip, TestOutcome, TestResult, test, each
 from tests.utilities import NUMBER_OF_TESTS, testable_test, example_test, module