Merge pull request #121 from scidash/docs

Merge docs into Dev

docs/README.md

@@ -0,0 +1,16 @@
+# Recipe for building the API docs from scratch:
+
+updating .rst files with sphinx-apidoc
+
+shell commands:
+```
+rm -rf source
+sphinx-apidoc -o "./source" "../sciunit"
+sphinx-quickstart
+```
+
+Copy conf.py from the oringinal sciunit repo. Then:
+
+```
+sphinx-build -b html ./source ./build
+```

docs/chapter1.ipynb

@@ -145,7 +145,7 @@
     "'''\n",
     "import sciunit\n",
     "from .tests import position_test, velocity_test, eccentricity_test\n",
-    "saturn_motion_suite = sciunit.TestSuite([position_test, velocity_test, eccentricity_test)]\n",
+    "saturn_motion_suite = sciunit.TestSuite([position_test, velocity_test, eccentricity_test])\n",
     "suites = (saturn_motion_suite,)\n",
     "```"
    ]

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/conf.py

@@ -161,3 +161,15 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}
+
+# Removing those three member from the documents to avoid mess. More members can be added in the future.
+def remove_variables(app, what, name, obj, skip, options):
+    if name == "_url":
+        print("-----------------------")
+        print(what)
+    excluded = ["normalization_rules", "rules", "validation_rules", "__dict__", "__doc__"]
+    return name in excluded
+
+# Connecting remove_variables and autodoc-skip-member to setup the event handler.
+def setup(app):
+    app.connect('autodoc-skip-member', remove_variables)

docs/source/index.rst

@@ -1,9 +1,9 @@
-.. SciUnit documentation master file, created by
-   sphinx-quickstart on Fri Mar 31 23:49:49 2017.
+.. sciunit documentation master file, created by
+   sphinx-quickstart on Sat Dec 21 14:20:34 2019.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to SciUnit's documentation!
+Welcome to sciunit's documentation!
 ===================================
 
 .. toctree::

docs/source/sciunit.models.rst

@@ -0,0 +1,46 @@
+sciunit.models package
+======================
+
+Submodules
+----------
+
+sciunit.models.backends module
+------------------------------
+
+.. automodule:: sciunit.models.backends
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+sciunit.models.base module
+--------------------------
+
+.. automodule:: sciunit.models.base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+sciunit.models.examples module
+------------------------------
+
+.. automodule:: sciunit.models.examples
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+sciunit.models.runnable module
+------------------------------
+
+.. automodule:: sciunit.models.runnable
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: sciunit.models
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/sciunit.rst

@@ -6,56 +6,90 @@ Subpackages
 
 .. toctree::
 
-    sciunit.tests
+   sciunit.models
+   sciunit.scores
+   sciunit.unit_test
 
 Submodules
 ----------
 
+sciunit.base module
+-------------------
+
+.. automodule:: sciunit.base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 sciunit.capabilities module
 ---------------------------
 
 .. automodule:: sciunit.capabilities
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 sciunit.converters module
 -------------------------
 
 .. automodule:: sciunit.converters
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
-sciunit.models module
+sciunit.errors module
 ---------------------
 
-.. automodule:: sciunit.models
-    :members:
-    :undoc-members:
-    :show-inheritance:
+.. automodule:: sciunit.errors
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
-sciunit.scores module
+sciunit.suites module
 ---------------------
 
-.. automodule:: sciunit.scores
-    :members:
-    :undoc-members:
-    :show-inheritance:
+.. automodule:: sciunit.suites
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+sciunit.tests module
+--------------------
+
+.. automodule:: sciunit.tests
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 sciunit.utils module
 --------------------
 
 .. automodule:: sciunit.utils
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+sciunit.validators module
+-------------------------
+
+.. automodule:: sciunit.validators
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+sciunit.version module
+----------------------
+
+.. automodule:: sciunit.version
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 
 Module contents
 ---------------
 
 .. automodule:: sciunit
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/sciunit.scores.rst

@@ -0,0 +1,54 @@
+sciunit.scores package
+======================
+
+Submodules
+----------
+
+sciunit.scores.base module
+--------------------------
+
+.. automodule:: sciunit.scores.base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+sciunit.scores.collections module
+---------------------------------
+
+.. automodule:: sciunit.scores.collections
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+sciunit.scores.collections\_m2m module
+--------------------------------------
+
+.. automodule:: sciunit.scores.collections_m2m
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+sciunit.scores.complete module
+------------------------------
+
+.. automodule:: sciunit.scores.complete
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+sciunit.scores.incomplete module
+--------------------------------
+
+.. automodule:: sciunit.scores.incomplete
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: sciunit.scores
+   :members:
+   :undoc-members:
+   :show-inheritance: