From 3a6a38ee2651f419714196605a597e93fb37fff9 Mon Sep 17 00:00:00 2001 From: Spill-Tea Date: Thu, 12 Jun 2025 19:59:10 -0700 Subject: [PATCH 1/4] sample extended readme --- README.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0862b29..55ef5c3 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,51 @@ # PyTemplate -Python Project Template +[![build status][buildstatus-image]][buildstatus-url] + +[buildstatus-image]: https://github.com/Spill-Tea/PyTemplate/actions/workflows/python-app.yml/badge.svg?branch=main +[buildstatus-url]: https://github.com/Spill-Tea/PyTemplate/actions?query=branch%3Amain + +Python Project Template. Be sure to create a template directly +from github. + + +## Table of Contents +- [PyTemplate](#pytemplate) + - [Installation](#installation) + - [For Developers](#for-developers) + - [License](#license) + + +## Installation +Clone the repository and pip install. + +```bash +git clone https://github.com/Spill-Tea/PyTemplate.git +cd PyTemplate +pip install . +``` + +Alternatively, you may install directly from github. +```bash +pip install git+https://github.com/Spill-Tea/PyTemplate@main +``` + + +## For Developers +After cloning the repository, create a new virtual environment and run the following commands: + +```bash +pip install -e ".[dev]" +pre-commit install +pre-commit run --all-files +``` + +Running unit tests locally is straightforward with tox. Make sure +you have all python versions available required for your project +The `p` flag is not required, but it runs tox environments in parallel. +```bash +tox -p +``` +Be sure to run tox before creating a pull request. + +## License +[BSD-3](LICENSE) From eb0bef5373fc1d6b95c80fa66d3d52e9d7b7dbd1 Mon Sep 17 00:00:00 2001 From: Spill-Tea Date: Fri, 13 Jun 2025 00:29:59 -0700 Subject: [PATCH 2/4] Include sphinx documentation generation. --- docs/Makefile | 20 ++++++++++++++++++++ docs/make.bat | 35 +++++++++++++++++++++++++++++++++++ docs/source/api.rst | 5 +++++ docs/source/conf.py | 38 ++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 29 +++++++++++++++++++++++++++++ pyproject.toml | 2 +- tox.ini | 14 +++++++++----- 7 files changed, 137 insertions(+), 6 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/api.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 0000000..b8bc495 --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,5 @@ +API +=== + +.. autosummary:: + :toctree: generated diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..999c094 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,38 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information +import os +import sys + + +sys.path.insert(0, os.path.abspath("../src/")) + + +project = "PyTemplate" +copyright = "2025, Jason C Del Rio (Spill-Tea)" +author = "Jason C Del Rio (Spill-Tea)" +release = "v0.0.1" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.duration", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", +] + +templates_path = ["_templates"] +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "sphinx_rtd_theme" +html_static_path = ["_static"] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..c3dfcb9 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,29 @@ +.. PyTemplate documentation master file, created by + sphinx-quickstart on Thu Jun 12 22:11:46 2025. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +PyTemplate documentation +======================== + +Add your content using ``reStructuredText`` syntax. See the +`reStructuredText `_ +documentation for details. + +.. automodule:: PyTemplate.__init__ + :members: + :undoc-members: + :show-inheritance: + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + api + + +Indices and tables +================== +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 564321a..1811b0f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -34,7 +34,7 @@ exclude = ["benchmarks", "docs", "tests"] [project.optional-dependencies] dev = ["PyTemplate[doc,test,lint,type]", "tox", "pre-commit"] -doc = ["pdoc"] +doc = ["sphinx", "sphinx-rtd-theme"] test = ["pytest", "coverage", "pytest-xdist"] lint = ["pylint", "ruff"] type = ["mypy"] diff --git a/tox.ini b/tox.ini index 1c83b76..2b170b3 100644 --- a/tox.ini +++ b/tox.ini @@ -1,6 +1,6 @@ [tox] requires = tox>=4 -envlist = type, lint, coverage, py{38,39,310,311,312}-tests +envlist = type, lint, coverage, docs, py{38,39,310,311,312}-tests [testenv] description = Base Environment @@ -42,7 +42,11 @@ commands = ruff format --check --config pyproject.toml {posargs: src} pylint --rcfile pyproject.toml {posargs: src} -; [testenv:docs] -; changedir = doc -; extras = docs -; commands = sphinx-build -W -b html -d {envtmpdir}/doctrees . {envtmpdir}/html +[testenv:docs] +changedir = docs +extras = doc +allowlist_externals = rm +commands = + sphinx-build -W -b html -d {envtmpdir}/doctrees source {envtmpdir}/html +commands_post = + rm -rf {envtmpdir} From b709009490c53c03bf39ed14453dbab4892021d3 Mon Sep 17 00:00:00 2001 From: Spill-Tea Date: Fri, 13 Jun 2025 00:39:31 -0700 Subject: [PATCH 3/4] Include documentation build test as part of style CI step. --- .github/workflows/python-app.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/python-app.yml b/.github/workflows/python-app.yml index 44d3f1f..9d4d723 100644 --- a/.github/workflows/python-app.yml +++ b/.github/workflows/python-app.yml @@ -19,7 +19,7 @@ jobs: - name: Checkout PyTemplate Project uses: actions/checkout@v4 - - name: Set up Python ${{ matrix.python-version }} + - name: Set up Python uses: actions/setup-python@v5 with: python-version-file: .python-version-default @@ -38,6 +38,9 @@ jobs: if: always() run: tox -e type + - name: Confirm Documentation Builds + run: tox -e docs + tests: runs-on: ubuntu-latest strategy: From a1b34cd49b2b5fd5b84fbf38714125eb74191bcd Mon Sep 17 00:00:00 2001 From: Spill-Tea Date: Fri, 13 Jun 2025 01:14:11 -0700 Subject: [PATCH 4/4] add example custom css for documentation. --- docs/source/_static/custom.css | 5 +++++ docs/source/conf.py | 2 ++ 2 files changed, 7 insertions(+) create mode 100644 docs/source/_static/custom.css diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000..10930d7 --- /dev/null +++ b/docs/source/_static/custom.css @@ -0,0 +1,5 @@ +@import url("https://fonts.googleapis.com/css?family=Space Grotesk:wght@400;700&display=swap"); + +body { + font-family: 'Space Grotesk', sans-serif; +} diff --git a/docs/source/conf.py b/docs/source/conf.py index 999c094..1387eae 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -22,6 +22,7 @@ extensions = [ "sphinx.ext.duration", + "sphinx.ext.viewcode", "sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.napoleon", @@ -36,3 +37,4 @@ html_theme = "sphinx_rtd_theme" html_static_path = ["_static"] +html_css_files = ["custom.css"]