presents more docs

Makefile

@@ -19,8 +19,9 @@ OPEN_COMMAND		:= open
 endif
 export SURE_NO_COLORS	:= true
 export SURE_LOG_FILE	:= $(GIT_ROOT)/sure-$(date +"%Y-%m-%d-%H:%M:%S").log
+AUTO_STYLE_TARGETS	:= sure/runtime.py sure/runner.py sure/meta.py sure/meta.py sure/reporter.py sure/reporters
+export SURE_DISABLE_NEW_SYNTAX	:= true
 
-AUTO_STYLE_TARGETS	:= sure/runtime.py sure/runner.py sure/meta.py sure/meta.py sure/reporter.py sure/reporters sure/actors.py sure/agents.py
 ######################################################################
 # Phony targets (only exist for typing convenience and don't represent
 #                real paths as Makefile expects)
@@ -44,8 +45,13 @@ dependencies:
 	@rm -f $(MAIN_CLI_PATH) # remove MAIN_CLI_PATH to trigger pip install
 	$(MAKE) develop setup
 
-docs:
+clean-docs:
+	@rm -rf docs/build
+
+html-docs: clean-docs
 	@(cd docs && make html)
+
+docs: html-docs
 	$(OPEN_COMMAND) docs/build/html/index.html
 
 test tests: clean | $(VENV)/bin/pytest # $(VENV)/bin/nosetests	# @$(VENV)/bin/nosetests --rednose --immediate -vv --with-coverage --cover-package=sure
@@ -153,4 +159,6 @@ $(REQUIREMENTS_PATH):
 	run \
 	test \
 	tests \
+	clean-docs \
+	html-docs \
 	docs

docs/source/api-reference.rst

@@ -3,23 +3,102 @@
 API Reference
 =============
 
-API Builtin Documentation
--------------------------
+``sure``
+--------
 
-.. automodule:: sure
-   :members:
+.. py:module:: sure
 
-.. automodule:: sure.core
-   :members:
+.. autoclass:: sure.VariablesBag
 
-.. automodule:: sure.runner
-   :members:
+.. autoclass:: sure.CallBack
 
-.. automodule:: sure.importer
-   :members:
+.. autofunction:: sure.that_with_context
 
-.. automodule:: sure.importer
-   :members:
+.. autofunction:: sure.within
 
-.. automodule:: sure.old
-   :members:
+.. autofunction:: sure.word_to_number
+
+.. autofunction:: sure.assertionmethod
+
+.. autofunction:: sure.assertionproperty
+
+.. autoclass:: sure.IdentityAssertion
+
+.. autoclass:: sure.AssertionBuilder
+
+.. autofunction:: sure.assertion
+
+.. autofunction:: sure.chain
+
+.. autofunction:: sure.chainproperty
+
+.. autoclass:: sure.ensure
+
+.. autofunction:: sure.do_enable
+
+.. autofunction:: sure.enable
+
+
+``sure.core``
+-------------
+
+.. py:module:: sure.core
+
+.. autoclass:: sure.core.DeepExplanation
+
+.. autoclass:: sure.core.DeepComparison
+
+.. autofunction:: sure.core._get_file_name
+
+.. autofunction:: sure.core._get_line_number
+
+.. autofunction:: sure.core.itemize_length
+
+
+``sure.runner``
+---------------
+
+.. py:module:: sure.runner
+
+.. autoclass:: sure.runner.Runner
+
+``sure.importer``
+-----------------
+
+.. py:module:: sure.importer
+
+.. autofunction:: sure.importer.resolve_path
+
+.. autofunction:: sure.importer.get_root_python_module
+
+.. autoclass:: sure.importer.importer
+
+
+``sure.reporter``
+---------------------
+
+.. py:module:: sure.reporter
+
+.. autoclass:: sure.reporter.Reporter
+
+
+``sure.reporters``
+------------------
+
+.. py:module:: sure.reporters
+
+.. autoclass:: sure.reporters.feature.FeatureReporter
+
+
+``sure.old``
+------------
+
+.. py:module:: sure.old
+
+.. autofunction:: sure.old.identify_callable_location
+
+.. autofunction:: sure.old.is_iterable
+
+.. autofunction:: sure.old.all_integers
+
+.. autofunction:: sure.old.explanation

docs/source/conf.py

@@ -1,6 +1,7 @@
 import sys
 import os
 import sphinx_rtd_theme
+os.environ['SURE_DISABLE_NEW_SYNTAX'] = 'true'
 
 extensions = [
     "sphinx.ext.autodoc",
@@ -13,22 +14,21 @@
     "sphinx.ext.viewcode",
 ]
 
-templates_path = ["sure_docs_templates"]
 source_suffix = ".rst"
 master_doc = "index"
 project = "sure"
 copyright = "2015-2023, Gabriel Falcão"
 author = "Gabriel Falcão"
-version = "2.1.0"
-release = "2.1.0"
-language = None
+version = "3.0.0a"
+release = "3.0.0a"
+language = 'en'
 exclude_patterns = []
 pygments_style = "sphinx"
 todo_include_todos = True
 
 html_theme = "sphinx_rtd_theme"
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-html_static_path = ["sure_docs_static"]
+# html_static_path = ["_static"]
 htmlhelp_basename = "sure_"
 latex_elements = {}
 latex_documents = [
@@ -42,8 +42,8 @@
         "Sure Documentation",
         author,
         "Sure",
-        "One line description of project.",
-        "Miscellaneous",
+        "utility belt for automated testing in python for python.",
+        "Automated Testing",
     ),
 ]
 epub_title = project

docs/source/guide.rst

@@ -117,7 +117,7 @@ Example: Multiple Setup and Teardown functions
 
 
 ``tests/test_filesystem.py``
-........................
+............................
 
 .. code:: python
 
@@ -197,14 +197,14 @@ this will give you and output like
 
 .. code:: bash
 
-    Difference:
+   Difference:
 
-      <root>
-    -   <a-tag with-attribute="one">AND A VALUE</a-tag>
-    ?                           --
-    +   <a-tag with-attribute="two">AND A VALUE</a-tag>
-    ?                          ++
-      </root>'''
+   <root>
+   -   <a-tag with-attribute="one">AND A VALUE</a-tag>
+   ?                           --
+   +   <a-tag with-attribute="two">AND A VALUE</a-tag>
+   ?                          ++
+   </root>
 
 ``.should.equal("a string")``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -400,7 +400,7 @@ And negate truthfulness:
 
 
 ``.have.property().being.*``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+............................
 
 If the programmer calls ``have.property()`` it returns an assertion
 builder of the property if it exists, so that you can chain up
@@ -426,7 +426,7 @@ assertions for the property value itself.
     basket3.should.have.key("fruits")
 
 ``.have.key().being.*``
-^^^^^^^^^^^^^^^^^^^^^^^
+.......................
 
 If the programmer calls ``have.key()`` it returns an assertion builder
 of the key if it exists, so that you can chain up assertions for the
@@ -478,7 +478,7 @@ Callables
 
 
 ``callable.when.called_with(arg1, kwarg1=2).should.have.raised(Exception)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can use this feature to assert that a callable raises an exception:
 
@@ -488,7 +488,7 @@ You can use this feature to assert that a callable raises an exception:
     range.when.called_with(10).should_not.throw(TypeError)
 
 Regular Expression matching on the exception message
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+....................................................
 
 You can also match regular expressions with to the expected exception
 messages:
@@ -547,7 +547,7 @@ this takes a type name and checks if the class matches that name
     range(10).should.be.a('collections.Iterable')
 
 ``.be.a(type)``
-~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~
 
 this takes the class (type) itself and checks if the object is an
 instance of it
@@ -593,7 +593,7 @@ Too long, don't read
 
 
 All those possibilities below work just as the same
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+...................................................
 
 .. code:: python
 
@@ -608,7 +608,7 @@ All those possibilities below work just as the same
 
 
 Also if you prefer using the assert keyword in your tests just go ahead an do it!
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.................................................................................
 
 Every assertion returns ``True`` when succeeded, and if failed the
 AssertionError is already raised internally by sure, with a nice
@@ -641,8 +641,8 @@ Test if something is or not callable
     (123).should_not.be.callable
 
 
-A note about the assert keyword
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A note about the ``assert`` keyword
+...................................
 
 .. note:: *you can use or not the* ``assert`` *keyword, sure
           internally already raises an appropriate* ``AssertionError`` *with an
@@ -765,7 +765,7 @@ Negative boolean synonyms
     None.should_not.be.ok
 
 Holy guacamole, how did you implement that feature ?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+....................................................
 
 Differently of `ruby <http://www.ruby-lang.org>`__ python doesn't have
 `open classes