Add documentation and update references

.gitignore

@@ -7,3 +7,4 @@ venv
 
 dist/
 *.egg-info/
+doc_generator/_static/

.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  -
+    repo: https://github.com/PyCQA/isort
+    rev: '5.12.0'
+    hooks:
+      -
+        id: isort
+
+  -
+    repo: local
+    hooks:
+      -
+        id: docs
+        name: docs
+        entry: /bin/bash gen_docs.sh
+        language: system
+        pass_filenames: false
+        always_run: true

README.md

@@ -101,10 +101,6 @@ engine.runAndWait()
 
 ```
 
-### Full documentation of the Library
-
-https://pyttsx3.readthedocs.io/en/latest/
-
 #### Included TTS engines
 
 * sapi5
@@ -117,7 +113,7 @@ Feel free to wrap another text-to-speech engine for use with ``pyttsx3``.
 
 * PyPI (https://pypi.org/project/py3-tts/)
 * GitHub (https://github.com/thevickypedia/py3-tts)
-* Full Documentation (https://pyttsx3.readthedocs.org)
+* Full Documentation (https://py3-tts.vigneshrao.com/)
 
 ### Credits
 

doc_generator/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = python3 -m sphinx
+SPHINXPROJ    = pyttsx3
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc_generator/conf.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# pyttsx3 documentation build configuration file, created by
+# sphinx-quickstart on Sun Jun 25 11:19:31 2017.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+import pyttsx3
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# 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('.'))
+
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# 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']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'py3-tts'
+copyright = '2022, Vignesh S Rao'
+author = 'Vignesh S Rao'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = pyttsx3.version
+# The full version, including alpha/beta/rc tags.
+release = pyttsx3.version
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'en'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# 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,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'pyttsx3doc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'pyttsx3.tex', 'pyttsx3 Documentation',
+     'Natesh M Bhat', 'manual'),
+]
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'pyttsx3', 'pyttsx3 Documentation',
+     [author], 1)
+]
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'pyttsx3', 'pyttsx3 Documentation',
+     author, 'pyttsx3', 'One line description of project.',
+     'Miscellaneous'),
+]

doc_generator/drivers.rst

@@ -0,0 +1,102 @@
+Implementing drivers
+--------------------
+
+You can implement new drivers for the :mod:`pyttsx3.Engine` by:
+
+#. Creating a Python module with the name of your new driver.
+#. Implementing the required driver factory function and class in your module.
+#. Using methods on a :class:`pyttsx3.driver.DriverProxy` instance provided by the :class:`pyttsx3.Engine` to control the event queue and notify applications about events.
+
+The Driver interface
+~~~~~~~~~~~~~~~~~~~~
+
+All drivers must implement the following factory function and driver interface.
+
+.. module:: pyttsx3.drivers
+   :synopsis: The package containing the available driver implementations
+
+.. function:: buildDriver(proxy : pyttsx3.driver.DriverProxy) -> pyttsx3.drivers.DriverDelegate
+
+   Instantiates delegate subclass declared in this module.
+
+   :param proxy: Proxy instance provided by a :class:`pyttsx3.Engine` instance.
+
+.. class:: DriverDelegate
+
+   .. note:: The :class:`DriverDelegate` class is not actually declared in :mod:`pyttsx3.drivers` and cannot serve as a base class. It is only here for the purpose of documenting the interface all drivers must implement.
+
+   .. method:: __init__(proxy : pyttsx3.drivers.DriverProxy, *args, **kwargs) -> None
+
+      Constructor. Must store the proxy reference.
+
+      :param proxy: Proxy instance provided by the :func:`buildDriver` function.
+
+   .. method:: destroy() ->
+
+      Optional. Invoked by the :class:`pyttsx3.driver.DriverProxy` when it is being destroyed so this delegate can clean up any synthesizer resources. If not implemented, the proxy proceeds safely.
+
+   .. method:: endLoop() -> None
+
+      Immediately ends a running driver event loop.
+
+   .. method:: getProperty(name : string) -> object
+
+      Immediately gets the named property value. At least those properties listed in the :meth:`pyttsx3.Engine.getProperty` documentation must be supported.
+
+      :param name: Name of the property to query.
+      :return: Value of the property at the time of this invocation.
+
+   .. method:: say(text : unicode, name : string) -> None
+
+      Immediately speaks an utterance. The speech must be output according to the current property values applied at the time of this invocation. Before this method returns, it must invoke :meth:`pyttsx3.driver.DriverProxy.setBusy` with value :const:`True` to stall further processing of the command queue until the output completes or is interrupted.
+
+      This method must trigger one and only one `started-utterance` notification when output begins, one `started-word` notification at the start of each word in the utterance, and a `finished-utterance` notification when output completes.
+
+      :param text: Text to speak.
+      :param name: Name to associate with the utterance. Included in notifications about this utterance.
+
+   .. method:: setProperty(name : string, value : object) -> None
+
+      Immediately sets the named property value. At least those properties listed in the :meth:`pyttsx3.Engine.setProperty` documentation must be supported. After setting the property, the driver must invoke :meth:`pyttsx3.driver.DriverProxy.setBusy` with value :const:`False` to pump the command queue.
+
+      :param name: Name of the property to change.
+      :param value: Value to set.
+
+   .. method:: startLoop()
+
+      Immediately starts an event loop. The loop is responsible for sending notifications about utterances and pumping the command queue by using methods on the :class:`pyttsx3.driver.DriverProxy` object given to the factory function that created this object.
+
+   .. method:: stop()
+
+      Immediately stops the current utterance output. This method must trigger a `finished-utterance` notification if called during on-going output. It must trigger no notification if there is no ongoing output. 
+
+      After stopping the output and sending any required notification, the driver must invoke :meth:`pyttsx3.driver.DriverProxy.setBusy` with value :const:`False` to pump the command queue.
+
+The DriverProxy interface
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. module:: pyttsx3.driver
+   :synopsis: The module containing the driver proxy implementation
+
+The :func:`pyttsx3.drivers.buildDriver` factory receives an instance of a :class:`DriverProxy` class and provides it to the :class:`pyttsx3.drivers.DriverDelegate` it constructs. The driver delegate can invoke the following public methods on the proxy instance. All other public methods found in the code are reserved for use by an :class:`pyttsx3.Engine` instance.
+
+.. class:: DriverProxy
+
+   .. method:: isBusy() -> bool
+
+      Gets if the proxy is busy and cannot process the next command in the queue or not.
+
+      :return: True means busy, False means idle.
+
+   .. method:: notify(topic : string, **kwargs) -> None
+
+      Fires a notification.
+
+      :param topic: The name of the notification.
+      :kwargs: Name/value pairs associated with the topic.
+
+   .. method:: setBusy(busy : bool) -> None
+
+      Sets the proxy to busy so it cannot continue to pump the command queue or idle so it can process the next command.
+
+      :param busy: True to set busy, false to set idle