diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..eec2659 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,50 @@ +# Workflow for building sphinx documentation remotely +# and deploying the static HTML to a GitHub Pages site. +# Note this approach does not require the static HTML +# files to be stored/pushed/committed to an alternate +# pages branch or anything like that. It uses GitHub +# Action artifacts... +name: Build and Deploy Sphinx Docs to GitHub Pages + +on: + push: + branches: + - main + - dev + release: + types: + - published + pull_request: + + # 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: read + pages: write + id-token: write + +# Allow one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + ## These help to install krank remotely + ## So it's importable in conf.py, but I + ## think this is solved with a relative + ## import now in conf.py. + # - name: Checkout + # uses: actions/checkout@v4 + # - name: Install package + # run: python -m pip install . + - name: Deploy to GitHub Pages + id: deployment + uses: sphinx-notes/pages@v3 diff --git a/docs/conf.py b/docs/conf.py index 98b5e54..f321c3c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,19 +6,25 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -import os +from pathlib import Path import time import sys from importlib.metadata import metadata +# Need to make sure that krank can be imported, and also that +# it is importing the local one (as opposed to a previously pip installed one). +# So this can be from the krank/src/krank directory or through a locally +# built or locally pip installed version. +# +# This prevents the need to build krank manually in the github action for pages. +# # autodoc needs to import your modules in order to extract the docstrings. # Therefore, you must add the appropriate path to sys.path in your conf.py. -sys.path.insert(0, os.path.abspath("../krank/src")) - +sys.path.insert(0, str(Path(__file__).parents[1].joinpath("src"))) import krank + project = krank.__name__ release = krank.__version__ # Full project version version = krank.__version__[:3] # Major project version @@ -106,14 +112,23 @@ {"name": "Contributing", "url": "https://github.com/remrama/krank#contributing"}, ], "header_links_before_dropdown": 4, + "navbar_start": ["navbar-logo", "navbar-icon-links"], # "version-switcher" + "navbar_center": ["navbar-nav"], + "navbar_end": [], + # "navbar_persistent": [], # Default is a nice search bubble that I otherwise don't get + "search_bar_text": "Search...", + # "article_header_start": ["breadcrumbs"], + # "article_header_end": [], + # "article_footer_items": [], + "footer_start": ["last-updated"], # "search-field" "search-button" + "footer_center": [], + "footer_end": [], # "theme-switcher" + "content_footer_items": [], + "show_prev_next": False, # "sidebarwidth": 230, # "navbar_start": ["navbar-logo", "version-switcher"], "show_version_warning_banner": True, "announcement": "BEWARE! This project is in the planning stage.", - # "navbar_end": ["theme-switcher", "navbar-icon-links"], - "navbar_end": ["navbar-icon-links"], - # "navbar_end": ["theme-switcher", "navbar-icon-links", "search-field"], - # "search_bar_text": "Search for something...", "navbar_align": "left", # [left, content, right] For testing that the navbar items align properly "show_nav_level": 3, "show_toc_level": 3, @@ -126,7 +141,7 @@ # "icon_links_label": "Quick Links", "icon_links": [ { - "name": "GitHub", + "name": "Krank on GitHub", "url": "https://github.com/remrama/krank", "icon": "fa-brands fa-square-github", "type": "fontawesome", diff --git a/docs/index.rst b/docs/index.rst index 2388d6c..c833408 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,6 +2,7 @@ .. image:: https://badge.fury.io/py/krank.svg :target: https://badge.fury.io/py/krank +---- Krank ===== diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..d8f56ef --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,10 @@ +# This is redundant with dev dependencies in pyproject.toml. +# It is used by the sphinx-notes/pages@v3 GitHub Action used +# to build the documentation remotely. It installs sphinx +# automatically, but need to add additional requirements +# that are installed during documentation building. +# +# There's a way to customize that GitHub action so maybe this +# could be avoided, but okay. + +pydata-sphinx-theme diff --git a/pyproject.toml b/pyproject.toml index 15e9046..9f4f8f2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -41,7 +41,7 @@ Homepage = "https://github.com/remrama/krank" [project.optional-dependencies] dev = [ "sphinx", - "pydata-sphinx-theme", + "pydata-sphinx-theme", # Needs to be in requirements.txt also (for docs.yml). ] [tool.setuptools]