initial documentation and related refactoring

it-spirit · Sep 27, 2020 · 2296aab · 2296aab
1 parent 11b4218
commit 2296aab
Show file tree

Hide file tree

Showing 24 changed files with 674 additions and 171 deletions.
diff --git a/HISTORY.rst b/HISTORY.rst
@@ -2,7 +2,7 @@
 History
 =======
 
-0.1.0 (2020-08-15)
+0.1.0 (2020-09-28)
 ------------------
 
-* First release on PyPI.
+* First (alpha) release on PyPI.
diff --git a/Makefile b/Makefile
@@ -68,9 +68,9 @@ coverage: ## check code coverage quickly with the default Python
 docs: ## generate Sphinx HTML documentation, including API docs
 	rm -f docs/questions.rst
 	rm -f docs/modules.rst
-	sphinx-apidoc -o docs/ questions
+	sphinx-apidoc -e -o docs/ questions
 	$(MAKE) -C docs clean
-	$(MAKE) -C docs html
+	$(MAKE) -b spelling -C docs html
 	$(BROWSER) docs/_build/html/index.html
 
 servedocs: docs ## compile the docs watching for changes

diff --git a/docs/_static/README.txt b/docs/_static/README.txt
@@ -0,0 +1 @@
+Include static resources here.
diff --git a/docs/conf.py b/docs/conf.py
@@ -31,7 +31,12 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx_autodoc_typehints',
+    'sphinxcontrib.spelling',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -89,7 +94,13 @@
 # theme further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    "page_width": "1200px",
+    "github_user": "cguardia",
+    "github_repo": "questions",
+    "github_banner": "true",
+    "github_button": "false",
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -159,4 +170,8 @@
 ]
 
 
+# -- Options for spell checking ----------------------------------------
 
+# File containing list of words known to be spelled correctly, but not in
+# the dictionary.
+spelling_word_list_filename = 'spelling_word_list.txt'
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,6 +1,13 @@
 Welcome to Questions's documentation!
 ======================================
 
+Questions is a Python form library that uses the power of SurveyJS_ for the UI.
+The philosophy behind Questions is that modern form rendering usually requires
+integrating some complex Javascript widgets anyway, so why not skip the markup
+generation completely? 
+
+.. _SurveyJS: https://surveyjs.io
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:

diff --git a/docs/questions.cli.rst b/docs/questions.cli.rst
@@ -0,0 +1,7 @@
+questions.cli module
+====================
+
+.. automodule:: questions.cli
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/questions.form.rst b/docs/questions.form.rst
@@ -0,0 +1,7 @@
+questions.form module
+=====================
+
+.. automodule:: questions.form
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/questions.questions.rst b/docs/questions.questions.rst
@@ -0,0 +1,7 @@
+questions.questions module
+==========================
+
+.. automodule:: questions.questions
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/questions.rst b/docs/questions.rst
@@ -4,59 +4,20 @@ questions package
 Submodules
 ----------
 
-questions.cli module
---------------------
-
-.. automodule:: questions.cli
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-questions.form module
----------------------
-
-.. automodule:: questions.form
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-questions.questions module
---------------------------
-
-.. automodule:: questions.questions
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-questions.settings module
--------------------------
-
-.. automodule:: questions.settings
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-questions.templates module
---------------------------
-
-.. automodule:: questions.templates
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-questions.validators module
----------------------------
-
-.. automodule:: questions.validators
-    :members:
-    :undoc-members:
-    :show-inheritance:
+.. toctree::
+   :maxdepth: 4
 
+   questions.cli
+   questions.form
+   questions.questions
+   questions.settings
+   questions.templates
+   questions.validators
 
 Module contents
 ---------------
 
 .. automodule:: questions
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/questions.settings.rst b/docs/questions.settings.rst
@@ -0,0 +1,7 @@
+questions.settings module
+=========================
+
+.. automodule:: questions.settings
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/questions.templates.rst b/docs/questions.templates.rst
@@ -0,0 +1,7 @@
+questions.templates module
+==========================
+
+.. automodule:: questions.templates
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/questions.validators.rst b/docs/questions.validators.rst
@@ -0,0 +1,7 @@
+questions.validators module
+===========================
+
+.. automodule:: questions.validators
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/spelling_word_list.txt b/docs/spelling_word_list.txt
@@ -0,0 +1,18 @@
+cli
+darkblue
+darkrose
+docstring
+docstrings
+dropdown
+dropdowns
+javascript
+JQuery
+jquery
+ko
+repo
+submodules
+validator
+validators
+virtualenvwrapper
+vue
+winterstone