better docs

.github/workflows/documentation.yml

@@ -1,5 +1,5 @@
 # Simple workflow for deploying static content to GitHub Pages
-name: Generate and deploy documentation
+name: 📚 Generate and deploy documentation
 
 on:
   # Runs on pushes targeting the default branch

.github/workflows/release.yml

@@ -1,4 +1,4 @@
-name: Publish Python 🐍 distribution 📦 to PyPI
+name: 📦 Publish Python distribution to PyPI
 
 on:
   push:

.github/workflows/test.yml

@@ -1,4 +1,4 @@
-name: Tests
+name: 🧪 Tests
 
 on:
   push:

.gitignore

@@ -16,4 +16,6 @@ stubs
 # os & editor generated files
 .DS_Store
 .idea
-.vscode
+.vscode
+
+**/build

Makefile

@@ -13,12 +13,14 @@ test_coverage:
 	@uv run python -m pytest --junitxml=junit.xml  --cov-report term --cov-report xml:coverage.xml --cov=tikara
 
 safety:
-	@uv run safety scan --save-as html safety_scan.html
+	@uv run safety scan --save-as 
 
 docs:
-	@uv run sphinx-apidoc -f -o docs/source/ .
+	@uv run pydocstyle src
+	@uv run sphinx-apidoc -f -o docs/source/ . "test*"
 	@uv run sphinx-build -b html docs/source/ docs/build/html
 
+
 prepush: ruff test test_coverage safety
 
 .PHONY: stubs ruff test test_coverage safety docs prepush

README.md

@@ -30,7 +30,9 @@ content, metadata = tika.parse("document.pdf")
 
 🌈 **1682 supported media types and counting!**
 
-[🔍 See the full list →](/SUPPORTED_MIME_TYPES.md)
+[🔍 See the full list →](
+[Example Jupyter Notebooks](https://github.com/baughmann/tikara/tree/master/SUPPORTED_MIME_TYPES.md) 📔
+)
 
 ## 🛠 Installation
 
@@ -187,7 +189,7 @@ For detailed documentation on:
 - Custom JAR integration
 - Performance optimization
 
-See [ADVANCED.md](ADVANCED.md)
+See the [Example Jupyter Notebooks](https://github.com/baughmann/tikara/tree/master/examples) 📔
 
 ## 🎯 Inspiration
 
@@ -270,4 +272,4 @@ See [API Documentation](https://tikara.readthedocs.io/) for complete details.
 
 ## 📄 License
 
-Apache License 2.0 - See [LICENSE](LICENSE) for details.
+Apache License 2.0 - See [LICENSE](https://raw.githubusercontent.com/baughmann/tikara/refs/heads/master/LICENSE.txt) for details.

docs/source/_static/custom.css

@@ -0,0 +1,5 @@
+header img {
+  width: 35px;
+  height: 35px;
+  filter: invert(0%) !important;
+}

docs/source/conf.py

@@ -1,97 +1,97 @@
 import os
 import sys
 
+# Add source directory to path
 sys.path.insert(0, os.path.abspath("../../src"))
 
-project = "tikara"
+# Project information
+project = "Tikara"
 copyright = "2024, Nick Baughman"  # noqa: A001
 author = "Nick Baughman"
 
+master_doc = "index"
+
 # -- General configuration ---------------------------------------------------
 extensions = [
     # Core Sphinx extensions
-    "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
-    "sphinx.ext.doctest",
     "sphinx.ext.autosectionlabel",
-    "sphinx.ext.todo",
-    "sphinx.ext.duration",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.coverage",
-    "sphinx.ext.graphviz",
-    "sphinx.ext.autosummary",
+    # AutoAPI for automatic API documentation
+    "autoapi.extension",
     # Third-party extensions
     "myst_parser",
-    "sphinx_autodoc_typehints",
-    "sphinx_copybutton",
-    "sphinx_git",
-    "sphinxemoji.sphinxemoji",
-    "sphinx_sitemap",
-]
+    'sphinx.ext.doctest',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autodoc.typehints",
+    "sphinx_design"
 
-# Create _static directory if it doesn't exist
-os.makedirs("docs/source/_static", exist_ok=True)
+]
 
+# Paths
 templates_path = ["_templates"]
 exclude_patterns = ["test*"]
-sphinxemoji_style = "twemoji"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
 
-# Intersphinx configuration
-intersphinx_mapping = {
-    "python": ("https://docs.python.org/3", None),
-    "requests": ("https://requests.readthedocs.io/en/latest/", None),
-}
+# Create _static directory if it doesn't exist
+os.makedirs("_static", exist_ok=True)
+
+# AutoAPI configuration
+autoapi_type = "python"
+autoapi_dirs = ["../../src"]  # Adjust this path to your source directory
+autoapi_add_toctree_entry = True  # Avoid automatic addition to the toctree
+autoapi_keep_files = False  # Keeps the generated .rst files out of the docs folder
+autoapi_options = [
+    "members",
+    "show-inheritance",
+    "show-module-summary",
+    "imported-members",
+    "special-members",
+]
+autoapi_python_class_content = "both"
+
+# Enable MyST parser and configure Markdown support
+myst_enable_extensions = [
+    "colon_fence",  # Enables ::: for fences
+    "deflist",      # Enables definition lists
+]
+myst_heading_anchors = 3  # Auto-generate anchors for up to level 3 headings
+
+# Auto-section labeling
+autosectionlabel_prefix_document = True
+autosectionlabel_maxdepth = None
+highlight_language = 'python3'
+
+# Suppress warnings for duplicate labels
+suppress_warnings = ["autosectionlabel.*"]
+
+html_logo ="https://raw.githubusercontent.com/baughmann/tikara/refs/heads/master/tikara_logo.svg"
 
-# AutoDoc configuration
-autodoc_default_options = {
-    "members": True,
-    "member-order": "bysource",
-    "special-members": "__init__",
-    "undoc-members": True,
-    "exclude-members": "__weakref__",
-}
 
-# Primary domain
-primary_domain = "py"
 
 # -- Options for HTML output -------------------------------------------------
 html_baseurl = "https://baughmann.github.io/tikara/"
 html_theme = "sphinxawesome_theme"
-html_permalinks_icon = "<span>#</span>"
-html_static_path = ["_static"]
-sitemap_url_scheme = "{link}"
-
 
-# Theme options
 html_theme_options = {
     "show_breadcrumbs": True,
     "show_prev_next": True,
-    "show_toc_level": 3,
-    "navbar_title": "tikara",
-}
-
-# Enable todos
-todo_include_todos = True
-todo_emit_warnings = True
-
-# Better section anchors
-html_permalinks = True
-# Disable warning about duplicate labels
-suppress_warnings = ["autosectionlabel.*"]
 
-autosectionlabel_prefix_document = True
-autosectionlabel_maxdepth = None
-
-# Configure myst parser to avoid duplicate labels
-myst_heading_anchors = 3
+    "logo_light": "https://raw.githubusercontent.com/baughmann/tikara/refs/heads/master/tikara_logo.svg",
+    "logo_dark": "https://raw.githubusercontent.com/baughmann/tikara/refs/heads/master/tikara_logo.svg",
 
+    "extra_header_link_icons": {
+        "github": {
+            "icon": """<svg height="26px" style="margin-top:-2px;display:inline" viewBox="0 0 45 44" fill="currentColor" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M22.477.927C10.485.927.76 10.65.76 22.647c0 9.596 6.223 17.736 14.853 20.608 1.087.2 1.483-.47 1.483-1.047 0-.516-.019-1.881-.03-3.693-6.04 1.312-7.315-2.912-7.315-2.912-.988-2.51-2.412-3.178-2.412-3.178-1.972-1.346.149-1.32.149-1.32 2.18.154 3.327 2.24 3.327 2.24 1.937 3.318 5.084 2.36 6.321 1.803.197-1.403.759-2.36 1.379-2.903-4.823-.548-9.894-2.412-9.894-10.734 0-2.37.847-4.31 2.236-5.828-.224-.55-.969-2.759.214-5.748 0 0 1.822-.584 5.972 2.226 1.732-.482 3.59-.722 5.437-.732 1.845.01 3.703.25 5.437.732 4.147-2.81 5.967-2.226 5.967-2.226 1.185 2.99.44 5.198.217 5.748 1.392 1.517 2.232 3.457 2.232 5.828 0 8.344-5.078 10.18-9.916 10.717.779.67 1.474 1.996 1.474 4.021 0 2.904-.027 5.247-.027 5.96 0 .58.392 1.256 1.493 1.044C37.981 40.375 44.2 32.24 44.2 22.647c0-11.996-9.726-21.72-21.722-21.72" fill="currentColor"></path></svg>""",
+            "link": "https://github.com/baughmann/tikara"
+         }
+    }
+}
 
-# Configure MyST for README parsing
-myst_enable_extensions = [
-    "colon_fence",
-    "deflist",
-]
+# Permalinks
+html_permalinks = True
+html_permalinks_icon = "<span>#</span>"
 
-# Handle escaping in test module names
-python_use_unqualified_type_names = True
+# Copy-button configuration
+todo_include_todos = False  # Disabled for now, re-enable if needed

docs/source/index.rst

@@ -1,21 +1,26 @@
-Welcome to tikara's documentation!
-=====================================
-
-Overview
---------
+Welcome to Tikara's documentation!
+==================================
 
 .. include:: readme.rst
 
 API Reference
-============
-
+=============
 .. toctree::
-   :maxdepth: 2
-   :caption: API Documentation
+    :maxdepth: 4
+    :caption: Contents:
 
-   tikara
+    autoapi/index
 
+Additional Links
+================
 
+* `Home Page <index.html>`_
+* `API Overview <autoapi/index.html>`_
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
+
+External Resources
+==================
+* `Apache Tika Documentation <https://tika.apache.org/>`_
+* `GitHub Repository <https://github.com/baughmann/tikara>`_
+* `PyPI Project <https://pypi.org/project/tikara/>`_

docs/source/modules.rst

@@ -4,4 +4,3 @@ tikara
 .. toctree::
    :maxdepth: 4
 
-   test

docs/source/readme.rst

@@ -1,5 +1,2 @@
-README.md
-==========
-
 .. include:: ../../README.md
    :parser: myst_parser.sphinx_