From 2ce2981bc7c5d76b6931300d19ca36306fdca4f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Heinz-Alexander=20F=C3=BCtterer?= <35225576+afuetterer@users.noreply.github.com> Date: Tue, 21 Apr 2026 09:21:10 +0200 Subject: [PATCH 1/5] docs: restructure sphinx documentation --- .github/workflows/documentation.yml | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index a76160ab..8f6ce949 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -29,22 +29,23 @@ jobs: url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest steps: - - name: Checkout - uses: actions/checkout@v4 - - name: Install dependencies - run: | - python -m pip install --upgrade pip + - uses: actions/checkout@v6 + - uses: actions/setup-python@v6 + with: + python-version: "3.14" + - run: | + python -m python -m pip install --upgrade pip python -m pip install . --group=docs - name: Sphinx APIDoc run: | - sphinx-apidoc -f -o docs/source/ . + sphinx-apidoc --force -o docs/source/ . - name: Sphinx build run: | - sphinx-build -b html docs/source/ docs/build/html + sphinx-build --builder html docs/source/ docs/build/html - name: Setup Pages uses: actions/configure-pages@v5 - name: Upload artifact - uses: actions/upload-pages-artifact@v3 + uses: actions/upload-pages-artifact@v4 with: # Upload entire repository path: './docs/build/html' From 3001b4319a8e88edf4c1b66ba42bce87f4c74368 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Heinz-Alexander=20F=C3=BCtterer?= <35225576+afuetterer@users.noreply.github.com> Date: Mon, 27 Apr 2026 08:53:32 +0200 Subject: [PATCH 2/5] add "documentation" to project.urls in pyproject.toml --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index 484cbd06..1cae4c48 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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" From 1bb6c4ebf1b61a1a8d5b3fc83ebfdb2d859fbb9e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Heinz-Alexander=20F=C3=BCtterer?= <35225576+afuetterer@users.noreply.github.com> Date: Mon, 27 Apr 2026 09:10:47 +0200 Subject: [PATCH 3/5] add link to github repo --- docs/source/conf.py | 36 +++++++++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 52d5608f..8147ed83 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -11,9 +11,9 @@ # 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" +copyright = "2024, Chris A. Mattmann" +author = "Chris A. Mattmann" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration @@ -26,16 +26,34 @@ "sphinx.ext.autosectionlabel", "sphinx.ext.todo", "sphinx.ext.duration", - "myst_parser" + "myst_parser", ] -templates_path = ['_templates'] -exclude_patterns = ['tika.tests*'] - +templates_path = ["_templates"] +exclude_patterns = ["tika.tests*"] # -- 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'] +html_theme = "furo" +html_static_path = ["_static"] +html_theme_options = { + "source_repository": "https://github.com/chrismattmann/tika-python", + "source_branch": "master", + "source_directory": "docs/source/", + "footer_icons": [ + { + "name": "GitHub", + "url": "https://github.com/chrismattmann/tika-python", + # Embedded SVG instructions from furo docs + # Ref: https://pradyunsg.me/furo/customisation/footer/#configuration + "html": """ + + + + """, + "class": "", + }, + ], +} From 8bb0ca8204ecf53596ea26ea4da1a74d5e407a79 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Heinz-Alexander=20F=C3=BCtterer?= <35225576+afuetterer@users.noreply.github.com> Date: Mon, 27 Apr 2026 09:12:18 +0200 Subject: [PATCH 4/5] ci --- .github/workflows/ci.yml | 3 ++ .github/workflows/documentation.yml | 50 ++++++++++++++++------------- 2 files changed, 30 insertions(+), 23 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index aff21cd7..027794fb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -64,3 +64,6 @@ jobs: with: parallel-finished: true base-path: tika + + docs: + uses: ./.github/workflows/documentation.yml diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 8f6ce949..74a23a4e 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -2,18 +2,14 @@ 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,33 +18,41 @@ 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: + runs-on: ubuntu-slim steps: - uses: actions/checkout@v6 - uses: actions/setup-python@v6 with: python-version: "3.14" + cache: 'pip' + - run: | - python -m python -m pip install --upgrade pip + python -m pip install --upgrade pip python -m pip install . --group=docs - - name: Sphinx APIDoc - run: | - sphinx-apidoc --force -o docs/source/ . - - name: Sphinx build - run: | + python -m pip list + + - run: | sphinx-build --builder html docs/source/ docs/build/html - - name: Setup Pages - uses: actions/configure-pages@v5 - - name: Upload artifact + + - name: Upload artifact (only on push to master) + if: github.event_name == 'push' && github.ref == 'refs/heads/master' uses: actions/upload-pages-artifact@v4 with: - # Upload entire repository path: './docs/build/html' + + deploy: + 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 From ed80a871905feaf6a3c07fd2d4021f2bb131f3bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Heinz-Alexander=20F=C3=BCtterer?= <35225576+afuetterer@users.noreply.github.com> Date: Mon, 27 Apr 2026 08:54:22 +0200 Subject: [PATCH 5/5] restructure docs --- .gitignore | 2 ++ docs/source/conf.py | 51 ++++++++++++++++++--------- docs/source/index.rst | 20 +++++------ docs/source/modules.rst | 8 ----- docs/source/readme.rst | 5 --- docs/source/tika.rst | 77 ----------------------------------------- 6 files changed, 44 insertions(+), 119 deletions(-) delete mode 100644 docs/source/modules.rst delete mode 100644 docs/source/readme.rst delete mode 100644 docs/source/tika.rst diff --git a/.gitignore b/.gitignore index ae442261..158f42bd 100644 --- a/.gitignore +++ b/.gitignore @@ -23,3 +23,5 @@ setup.cfg # Sphinx documentation docs/build/ +# auto-generated by sphinx-apidoc +docs/source/api/ diff --git a/docs/source/conf.py b/docs/source/conf.py index 8147ed83..c4b4176a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -3,49 +3,64 @@ # 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" +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", ] -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 +REPO_URL = "https://github.com/chrismattmann/tika-python" + html_theme = "furo" -html_static_path = ["_static"] +# html_static_path = ["_static"] + html_theme_options = { - "source_repository": "https://github.com/chrismattmann/tika-python", - "source_branch": "master", - "source_directory": "docs/source/", + "source_repository": REPO_URL, + # "source_branch": "master", + # "source_directory": "docs/source/", + "top_of_page_buttons": [], # Note: do not show edit and view buttons "footer_icons": [ { "name": "GitHub", - "url": "https://github.com/chrismattmann/tika-python", + "url": REPO_URL, # Embedded SVG instructions from furo docs # Ref: https://pradyunsg.me/furo/customisation/footer/#configuration "html": """ @@ -57,3 +72,5 @@ }, ], } +# html_copy_source = False +# html_show_sourcelink = False diff --git a/docs/source/index.rst b/docs/source/index.rst index dfc67b61..d249ffdb 100644 --- a/docs/source/index.rst +++ b/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 - readme - tika Indices and tables -================== +------------------ * :ref:`genindex` * :ref:`modindex` -* :ref:`search` diff --git a/docs/source/modules.rst b/docs/source/modules.rst deleted file mode 100644 index ed38b547..00000000 --- a/docs/source/modules.rst +++ /dev/null @@ -1,8 +0,0 @@ -tika-python -=========== - -.. toctree:: - :maxdepth: 4 - - setup - tika diff --git a/docs/source/readme.rst b/docs/source/readme.rst deleted file mode 100644 index 0492b12e..00000000 --- a/docs/source/readme.rst +++ /dev/null @@ -1,5 +0,0 @@ -README.md -========== - -.. include:: ../../README.md - :parser: myst_parser.sphinx_ diff --git a/docs/source/tika.rst b/docs/source/tika.rst deleted file mode 100644 index 9c0d9039..00000000 --- a/docs/source/tika.rst +++ /dev/null @@ -1,77 +0,0 @@ -tika package -============ - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - tika.tests - -Submodules ----------- - -tika.config module ------------------- - -.. automodule:: tika.config - :members: - :undoc-members: - :show-inheritance: - -tika.detector module --------------------- - -.. automodule:: tika.detector - :members: - :undoc-members: - :show-inheritance: - -tika.language module --------------------- - -.. automodule:: tika.language - :members: - :undoc-members: - :show-inheritance: - -tika.parser module ------------------- - -.. automodule:: tika.parser - :members: - :undoc-members: - :show-inheritance: - -tika.tika module ----------------- - -.. automodule:: tika.tika - :members: - :undoc-members: - :show-inheritance: - -tika.translate module ---------------------- - -.. automodule:: tika.translate - :members: - :undoc-members: - :show-inheritance: - -tika.unpack module ------------------- - -.. automodule:: tika.unpack - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: tika - :members: - :undoc-members: - :show-inheritance: