revise docs to flask sphinx template

docs/Makefile

@@ -1,12 +1,11 @@
 # Minimal makefile for Sphinx documentation
-#
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
+SOURCEDIR     = .
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:

docs/conf.py

@@ -0,0 +1,98 @@
+# All the existing imports here
+import os
+import packaging.version
+from pallets_sphinx_themes import get_version
+from pallets_sphinx_themes import ProjectLink
+from sphinx.ext.autodoc import ClassDocumenter
+from sphinx.application import Sphinx
+from sphinx.util.docstrings import prepare_docstring
+
+# Project --------------------------------------------------------------
+
+project = "konanai"
+copyright = "2023 KonanAI LLC"
+author = "Joseph Konan"
+release, version = get_version("konanai")
+
+# General --------------------------------------------------------------
+
+master_doc = "index"
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinxcontrib.log_cabinet",
+    "pallets_sphinx_themes",
+    "sphinx_issues",
+    "sphinx_tabs.tabs",
+]
+autodoc_typehints = "description"
+autodoc_default_options = {
+    'member-order': 'bysource',
+    'undoc-members': True,
+}
+add_module_names = False
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+}
+issues_github_path = "KonanAI-LLC/konanai"
+
+# HTML -----------------------------------------------------------------
+
+html_theme = "flask"
+html_theme_options = {"index_sidebar_logo": False}
+html_context = {
+    "project_links": [
+        ProjectLink("PyPI Releases", "https://pypi.org/project/konanai/"),
+        ProjectLink("Source Code", "https://github.com/KonanAI-LLC/konanai"),
+        ProjectLink("Issue Tracker", "https://github.com/KonanAI-LLC/konanai/issues/"),
+    ]
+}
+html_sidebars = {
+    "index": ["project.html", "localtoc.html", "searchbox.html"],
+    "**": ["localtoc.html", "relations.html", "searchbox.html"],
+}
+singlehtml_sidebars = {"index": ["project.html", "localtoc.html"]}
+html_static_path = ["_static"]
+html_favicon = "_static/shortcut-icon.png"
+html_logo = "_static/konanai-logo.png"
+html_title = f"konanai Documentation ({version})"
+html_show_sourcelink = False
+
+exclude_patterns = ['**/konanai/src/konanai/externals/lib']
+
+# LaTeX ----------------------------------------------------------------
+
+latex_documents = [(master_doc, f"konanai-{version}.tex", html_title, author, "manual")]
+
+# Local Extensions -----------------------------------------------------
+
+def github_link(name, rawtext, text, lineno, inliner, options=None, content=None):
+    app = inliner.document.settings.env.app
+    release = app.config.release
+    base_url = "https://github.com/KonanAI-LLC/konanai/tree/"
+
+    if text.endswith(">"):
+        words, text = text[:-1].rsplit("<", 1)
+        words = words.strip()
+    else:
+        words = None
+
+    if packaging.version.parse(release).is_devrelease:
+        url = f"{base_url}main/{text}"
+    else:
+        url = f"{base_url}{release}/{text}"
+
+    if words is None:
+        words = url
+
+    from docutils.nodes import reference
+    from docutils.parsers.rst.roles import set_classes
+
+    options = options or {}
+    set_classes(options)
+    node = reference(rawtext, words, refuri=url, **options)
+    return [node], []
+
+def setup(app: Sphinx):
+    app.add_role("gh", github_link)

docs/index.rst

@@ -0,0 +1,165 @@
+
+Konanai API
+===========
+
+.. module:: konanai
+
+This part of the documentation covers all the interfaces of konanai. For parts
+where konanai depends on external libraries, we document the most important
+right here and provide links to the canonical documentation.
+
+
+Domains Module
+--------------
+
+.. module:: konanai.domains
+
+This module provides diverse functionalities encompassing several critical
+domains integral to speech and language processing.
+
+.. automodule:: konanai.domains
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.domains.time.Time
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.domains.time.Waveform
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.domains.linguistic.LinguisticUnit
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.domains.linguistic.Phoneme
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.domains.linguistic.Word
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.domains.time_frequency.Spectrogram
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.domains.time_frequency.PowerSpectrogram
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.domains.time_linguistic.Alignment
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.domains.time_linguistic.WordAlignment
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.domains.time_linguistic.PhonemeAlignment
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.domains.time_linguistic.Transcript
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.domains.representation.DataHandler
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.domains.representation.Embedding
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.domains.representation.DecisionBoundary
+   :members:
+   :inherited-members:
+
+
+Externals Module
+----------------
+
+.. module:: konanai.externals
+
+This module provides intuitive, easy-to-use wrappers for several external tools
+integral to high-level speech and language processing tasks.
+
+.. automodule:: konanai.externals
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.externals.umap_wrapper.NonparametricUmap
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.externals.umap_wrapper.ParametricUmap
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.externals.opensmile_wrapper.BaseOpensmile
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.externals.opensmile_wrapper.EgemapsV2
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.externals.opensmile_wrapper.Compare2016
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.externals.charsiu_wrapper.ForcedAligner
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.externals.charsiu_wrapper.PredictiveAligner
+   :members:
+   :inherited-members:
+
+
+Models Module
+-------------
+
+.. module:: konanai.models
+
+This module provides a suite of estimators, forming the backbone of the machine
+learning capabilities within `konanai`.
+
+.. automodule:: konanai.models
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.models.acoustic_phonetic.BaseEstimator
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.models.acoustic_phonetic.AcousticEstimator
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.models.acoustic_phonetic.PhoneticEstimator
+   :members:
+   :inherited-members:
+
+
+Empirics Module
+---------------
+
+.. module:: konanai.empirics
+
+This module is designed to offer robust tools for conducting empirical analysis,
+an essential component of high-level language and speech processing research.
+
+.. automodule:: konanai.empirics
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.empirics.ablation.Results
+   :members:
+   :inherited-members:
+
+.. autoclass:: konanai.empirics.ablation.Ablation
+   :members:
+   :inherited-members:

docs/postprocess.py

@@ -0,0 +1,30 @@
+
+import sys
+
+def modify_html(file_path):
+    with open(file_path, 'r', encoding='utf8') as file:
+        html_content = file.read()
+
+    split_str_1 = '"><code class="docutils literal notranslate"><span class="pre">'
+    split_str_2 = "."
+
+    new_content = []
+    for line in html_content.split('\n'):
+        if split_str_1 in line:
+            s1, s2 = line.split(split_str_1)
+            if split_str_2 in s2:
+                s3, s4 = s2.split(split_str_2, 1)  # using 1 to split at the first dot only
+                new_line = "".join([s1, split_str_1, split_str_2, s4])
+                new_content.append(new_line)
+            else:
+                new_content.append(line)
+        else:
+            new_content.append(line)
+
+    html_content_modified = '\n'.join(new_content)
+
+    with open(file_path, 'w', encoding='utf8') as file:
+        file.write(html_content_modified)
+
+if __name__ == '__main__':
+    modify_html(sys.argv[1])