diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c73947b1..030e5b58 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,16 +1,19 @@ name: GitHub Pages -on: +on: # Always attempt html build on push & PR, but only deploy when there is a new tag. push: branches: - main + tags: + - v* pull_request: branches: - main - workflow_dispatch: + workflow_dispatch: # Allows to manually trigger the job from the web UI. jobs: - deploy: + build: + name: Build documentation (and deploy for git tag) runs-on: ubuntu-latest permissions: contents: write @@ -33,13 +36,10 @@ jobs: python3 -m venv .venv-gh-pages source .venv-gh-pages/bin/activate python3 -m pip install "$PWD"[doc,test] - pdoc -t docs/template -o html --math pydrex !pydrex.mesh !pydrex.distributed tests + make html - name: Deploy uses: peaceiris/actions-gh-pages@v4 - # If you're changing the branch from main, - # also change the `main` in `refs/heads/main` - # below accordingly. - if: ${{ github.ref == 'refs/heads/main' }} + if: ${{ startsWith(github.ref, 'refs/tags/') }} with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./html diff --git a/Makefile b/Makefile index 50a1139e..9d5d4126 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,9 @@ .SHELLFLAGS += -u .ONESHELL: MAKEFLAGS += --no-builtin-rules +VERSION = $(shell git describe) +# NOTE: Keep this at the top! Bare `make` should just build the sdist + bdist. dist: python -m build @@ -12,8 +14,15 @@ test: mkdir out pytest -v --outdir=out +html: + 2>pdoc.log pdoc -t docs/template -o html pydrex !pydrex.mesh !pydrex.distributed tests \ + --favicon "https://raw.githubusercontent.com/seismic-anisotropy/PyDRex/main/docs/assets/favicon32.png" \ + --footer-text "PyDRex $(VERSION)" + clean: - rm -r dist - rm -r out + rm -rf dist + rm -rf out + rm -rf html + rm -rf pdoc.log .PHONY: release test clean diff --git a/README.md b/README.md index 1554e735..8eabcc8f 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # PyDRex -

- PyDRex logo +

+ PyDRex logo

#### Simulate crystallographic preferred orientation evolution in polycrystals @@ -45,34 +45,27 @@ declared in the `pyproject.toml` file. ## Testing Running tests or examples requires a local git clone or unpacked source distribution. +Install test suite dependencies with `pip install '.[test]'`. Some tests can optionally output figures or extended diagnostics when run locally. -Testing locally requires a local git clone or source distribution of PyDRex. Check the `tests/README.md` file for details. Further examples that demonstrate how PyDRex can be used within geodynamic -simulations are provided in the `examples` folder. +simulations are provided in subfolders of the `examples` folder. They have their own README file as well. ## Building offline documentation -The documentation can be built offline using [pdoc](https://github.com/mitmproxy/pdoc), -with the command: +The documentation can be built offline from a git clone or source distribution. +Install documentation builder dependencies with `pip install '.[doc]'`. - pdoc -t docs/template -o html --math pydrex tests - -which will output the html documentation into a folder called `html`. +Run `make html` from the terminal to generate PyDRex's documentation +(available in the `html` directory), including the API reference. The homepage will be `html/index.html`. -Note that some submodules depend on optional dependencies, -and should otherwise be excluded: - - pdoc -t docs/template -o html --math pydrex !pydrex.mesh !pydrex.distributed tests - -See also the provided [GitHub actions workflow](https://raw.githubusercontent.com/seismic-anisotropy/PyDRex/main/.github/workflows/docs.yml). ## Contributing -For a development environment, clone the [source code](https://github.com/seismic-anisotropy/PyDRex) +For a Linux or MacOS development environment, clone the [source code](https://github.com/seismic-anisotropy/PyDRex) and execute the Bash script `tools/venv_install.sh`. This will set up a local Python virtual environment with an [editable install](https://setuptools.pypa.io/en/latest/userguide/development_mode.html) of PyDRex that can be activated/deactivated by following the displayed prompts. diff --git a/docs/assets/favicon32.png b/docs/assets/favicon32.png new file mode 100644 index 00000000..3035442e Binary files /dev/null and b/docs/assets/favicon32.png differ diff --git a/docs/assets/logo160.png b/docs/assets/logo160.png new file mode 100644 index 00000000..019a9cc4 Binary files /dev/null and b/docs/assets/logo160.png differ diff --git a/docs/assets/logo256.png b/docs/assets/logo256.png new file mode 100644 index 00000000..86b1cb13 Binary files /dev/null and b/docs/assets/logo256.png differ diff --git a/docs/assets/social.png b/docs/assets/social.png new file mode 100644 index 00000000..8d45b763 Binary files /dev/null and b/docs/assets/social.png differ diff --git a/docs/template/README.md b/docs/template/README.md new file mode 100644 index 00000000..dc1d0b43 --- /dev/null +++ b/docs/template/README.md @@ -0,0 +1,14 @@ +The docs template is modified from the default template found at: + + + +The most significant changes are: +- adding buttons to chose from API or tests/examples docs to the landing page +- switching to a dark CSS theme, based on the example found at the link below + + + +When pdoc releases a new version we should check +if there were any upstream template/theme changes that we want to merge. +It is not necessary to copy-paste template files that we don't intend to change, +as pdoc will automatically fall back to using the files from the default theme. diff --git a/docs/template/index.html.jinja2 b/docs/template/index.html.jinja2 index d9bb1acf..c1ab9959 100644 --- a/docs/template/index.html.jinja2 +++ b/docs/template/index.html.jinja2 @@ -3,8 +3,8 @@ {% block title %}PyDRex: Welcome{% endblock %} {% block nav %} - -

PyDRex

+ +

{{ footer_text }}


{% endblock %} diff --git a/tests/README.md b/tests/README.md index 7830a55d..49a40b35 100644 --- a/tests/README.md +++ b/tests/README.md @@ -1,7 +1,9 @@ # PyDRex tests -Running the tests requires [pytest](https://docs.pytest.org), and up to ~16GB RAM. -From the root of the source tree, run `pytest`. +Running the base test suite requires [pytest](https://docs.pytest.org) and up to ~16GB RAM. +By default, `make test` will attempt to write persistent logs and output to `./out/`. + +Alternatively, run `pytest` from the root of the source tree. To print more verbose information (including INFO level logging), such as detailed test progress, use the flag `pytest -v`. The custom optional flag `--outdir="OUT"` is recommended