Feature/issue 218/sphinx (#238)

* new docs

* api change

* more api automation changes.

* docs workflow

* build from branch

* link

* rm pdocs

* command change and duplicate code.

* deploy from gh-pages

* push to deploy

* actions change

* minimal actions, build on push

* single commit

* __doc__ link

* tutorial change

* homepage change.

* git ignore.

* reverting workflows to work off main.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* mistake.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* ruff lint ignore.

* mypy exclude

* linting

* indentation

* superfluous exclude patters.

* linting

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* new_tutorial

* remove old tutorial

* removing old files, updating settings.

* ignore notebooks

* notebook change

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* poetry lock file update.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* removing type ignores, updating toml to ignore notebook.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* update doc deps.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* lock file

* References

* supporterd formats

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update .github/workflows/docs.yaml

Co-authored-by: Adam Santorelli <148909356+Asanto32@users.noreply.github.com>

* workflow change

* doc change, makefil edits.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* lock file update.

* exclude notebooks from JSON hooks

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Adam Santorelli <148909356+Asanto32@users.noreply.github.com>

Author: 3 people

.gitattributes

@@ -0,0 +1,2 @@
+docs/source/tutorial_data/three_nights.bin filter=lfs diff=lfs merge=lfs -text
+*.ipynb filter=lfs diff=lfs merge=lfs -text

.github/workflows/docs.yaml

@@ -13,7 +13,6 @@ on:
 
 jobs:
   build-and-publish-docs:
-    if: ${{ github.event.workflow_run.conclusion == 'success' }}
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
@@ -26,10 +25,16 @@ jobs:
       run: |
         python -m pip install poetry
         poetry install --with docs
-    - name: Build docs
+    - name: Build Sphinx docs
+      working-directory: docs
       run: |
-        poetry run pdoc src/wristpy -o docs_build -t docs/pdoc-theme --docformat google
-        touch docs_build/.nojekyll
-    - uses: JamesIves/github-pages-deploy-action@6c2d9db40f9296374acc17b90404b6e8864128c8
+        poetry run make html
+        touch build/html/.nojekyll
+        ls -la build/html | sed 's/^/BUILD: /'
+    - name: Deploy to gh-pages
+      uses: JamesIves/github-pages-deploy-action@6c2d9db40f9296374acc17b90404b6e8864128c8
       with:
-        folder: docs_build
+        branch: gh-pages
+        folder: docs/build/html
+        clean: true
+        single-commit: true

.gitignore

@@ -76,6 +76,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/build/
+
 
 # PyBuilder
 .pybuilder/

.pre-commit-config.yaml

@@ -41,13 +41,15 @@ repos:
     - --fix=lf
   - id: trailing-whitespace
   - id: pretty-format-json
+    exclude: ^docs/source/.*\.ipynb$
     args:
     - --autofix
     - --indent=4
     - --no-sort-keys
   - id: check-merge-conflict
   - id: check-yaml
   - id: check-json
+    exclude: ^docs/source/.*\.ipynb$
   - id: check-toml
 
 - repo: local

README.md

@@ -1,6 +1,6 @@
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13883190.svg)](https://doi.org/10.5281/zenodo.13883190)
 
-# `wristpy` <img src="https://media.githubusercontent.com/media/childmindresearch/wristpy/main/docs/wristpy_logo.png" align="right" width="25%"/>
+# `wristpy` <img src="https://media.githubusercontent.com/media/childmindresearch/wristpy/main/docs/_static/images/wristpy_logo.png" align="right" width="25%"/>
 
  A Python package for wrist-worn accelerometer data processing.
 

docs/Makefile

@@ -0,0 +1,27 @@
+
+
+
+SPHINXOPTS    ?=
+SPHINXBUILD  ?= sphinx-build
+SOURCEDIR    = source
+BUILDDIR     = build
+
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+
+clean:
+	 @if [ -z "$(BUILDDIR)" ]; then \
+        echo "Error: BUILDDIR is not set."; \
+        exit 1; \
+    fi
+    rm -rf $(BUILDDIR)/*
+
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)