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 a76160ab..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,32 +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: - - 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@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 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 52d5608f..c4b4176a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -3,39 +3,74 @@ # 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_static_path = ["_static"] + +html_theme_options = { + "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": REPO_URL, + # Embedded SVG instructions from furo docs + # Ref: https://pradyunsg.me/furo/customisation/footer/#configuration + "html": """ + + + + """, + "class": "", + }, + ], +} +# 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: 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"