Merge pull request #484 from afuetterer/443-docs

docs: restructure sphinx documentation

Author: chrismattmann

.github/workflows/ci.yml

@@ -64,3 +64,6 @@ jobs:
       with:
         parallel-finished: true
         base-path: tika
+
+  docs:
+    uses: ./.github/workflows/documentation.yml

.github/workflows/documentation.yml

@@ -1,19 +1,14 @@
-# Simple workflow for deploying static content to GitHub Pages
 name: Documentation
 
 on:
-  # Runs on pushes targeting the default branch
   push:
     branches: ["master"]
-
+  workflow_call:
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-permissions:
-  contents: write
-  pages: write
-  id-token: write
+# Set permissions at the job level.
+permissions: {}
 
 # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
 # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
@@ -22,32 +17,43 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  # Single deploy job since we're just deploying
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
+  build:
+    name: Build documentation with Sphinx
+    runs-on: ubuntu-slim
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Install dependencies
-        run: |
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+          cache: 'pip'
+
+      - run: |
           python -m pip install --upgrade pip
           python -m pip install . --group=docs
-      - name: Sphinx APIDoc
-        run: |
-          sphinx-apidoc -f -o docs/source/ .
-      - name: Sphinx build
-        run: |
-          sphinx-build -b html docs/source/ docs/build/html
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+          python -m pip list
+
+      - run: |
+          sphinx-build --builder html docs/source/ docs/build/html
+
+      - name: Upload artifact (only on push to master)
+        if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+        uses: actions/upload-pages-artifact@v5
         with:
-          # Upload entire repository
           path: './docs/build/html'
+
+  deploy:
+    name: Deploy documentation to GitHub Pages
+    needs: build
+    # Deploy only on push to master
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-slim
+    steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

.gitignore

@@ -23,3 +23,5 @@ setup.cfg
 
 # Sphinx documentation
 docs/build/
+# auto-generated by sphinx-apidoc
+docs/source/api/

docs/source/conf.py

@@ -3,39 +3,69 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import importlib.metadata
+from datetime import datetime, timezone
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-import os
-import sys
-
-# Add the parent directory of the documentation root to sys.path
-sys.path.insert(0, os.path.abspath("../.."))
-
-project = 'tika-python'
-copyright = '2024, Chris A. Mattmann'
-author = 'Chris A. Mattmann'
+project = "tika-python"
+author = "Chris A. Mattmann"
+current_year = datetime.now(timezone.utc).astimezone().year
+copyright = f"{current_year}, {author}"
+version = importlib.metadata.version("tika")
+release = version
 
 # -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+# Ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.apidoc",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
     "sphinx.ext.doctest",
     "sphinx.ext.autosectionlabel",
-    "sphinx.ext.todo",
-    "sphinx.ext.duration",
-    "myst_parser"
+    "myst_parser",
 ]
 
-templates_path = ['_templates']
-exclude_patterns = ['tika.tests*']
+master_doc = "index"
+exclude_patterns = ["_build"]
 
+nitpicky = True
 
+# -- sphinx-apidoc configuration ---------------------------------------------------
+# Ref: https://www.sphinx-doc.org/en/master/usage/extensions/apidoc.html#confval-apidoc_modules
+apidoc_modules = [
+    {
+        "path": "../../tika",
+        "destination": "api",
+        "separate_modules": True,
+        "module_first": True,
+    },
+]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'furo'
-html_static_path = ['_static']
+REPO_URL = "https://github.com/chrismattmann/tika-python"
+
+html_theme = "furo"
+
+html_theme_options = {
+    "source_repository": REPO_URL,
+    "top_of_page_buttons": [], # Note: do not show edit and view buttons
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": REPO_URL,
+            # Embedded SVG instructions from furo docs
+            # Ref: https://pradyunsg.me/furo/customisation/footer/#configuration
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ],
+}

docs/source/index.rst

@@ -1,21 +1,17 @@
-.. tika-python documentation master file, created by
-   sphinx-quickstart on Sun Apr 14 20:07:31 2024.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
 
-Welcome to tika-python's documentation!
-=======================================
+Contents
+--------
 
 .. toctree::
-   :maxdepth: 7
-   :caption: Contents:
+   :maxdepth: 1
+
+   API <api/modules>
 
-   readme
-   tika
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`

docs/source/modules.rst

@@ -50,6 +50,7 @@ docs = [
 [project.urls]
 homepage = "http://github.com/chrismattmann/tika-python"
 repository = "http://github.com/chrismattmann/tika-python.git"
+documentation = "https://chrismattmann.github.io/tika-python"
 
 [project.scripts]
 tika-python = "tika.tika:main"