diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..4aebb384 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,38 @@ +name: Docs + +on: + push: + branches: + - main + - mkdocs + tags: + - '*' + +jobs: + build: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: actions/setup-python@v5 + with: + cache: pip + python-version: '3.11' + - run: make docs-deps + + - name: Configure the git user + run: | + git config user.name "Stealth Rocket" + git config user.email "bot@stealthrocket.tech" + + - name: Build main branch + if: ${{ github.ref_name == 'main' }} + run: | + mike deploy --push main + - name: Build tagged version + if: ${{ github.ref_name != 'main' }} + run: | + mike deploy --push --update-aliases ${{ github.ref_name }} latest diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c692499d..1e013ecb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,6 +26,16 @@ click around. You can refresh your browser after each `make coverage` run. Formatting is done with `black`. Run `make fmt`. -Docstrings follow the [Google style][docstrings]. +Docstrings follow the [Google style][docstrings]. All public entities should +have a docstring attached. [docstrings]: https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings + +## Documentation + +API reference documentation is automatically built on merges to `main` and new +tagged version. To view the generated documentation locally: + +``` +make local-docs +``` diff --git a/Makefile b/Makefile index 3d3a2ad6..47f86527 100644 --- a/Makefile +++ b/Makefile @@ -65,3 +65,10 @@ push: push-test: twine upload -r testpypi dist/* + + +docs-deps: dev + $(PYTHON) -m pip install .[docs] + +local-docs: docs-deps + mkdocs serve diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..01cdf98a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,23 @@ +--- +hide: + - navigation +--- + +# Dispatch Python SDK + +This is the API reference for the Python SDK of Dispatch. + +- Tutorials and guides: [docs.stealthrocket.tech][docs]. +- Source: [stealthrocket/dispatch-sdk][github]. + + +[docs]: https://docs.stealthrocket.tech +[github]: https://github.com/stealthrocket/dispatch-sdk + +## API Reference + +--- + +::: dispatch + options: + show_submodules: true diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..fe165e40 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,28 @@ +site_name: Dispatch SDK + +theme: + name: "material" + palette: + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch mode based on system preference + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode + +plugins: + - search + - mkdocstrings + - mike + +extra: + version: + provider: mike diff --git a/pyproject.toml b/pyproject.toml index d22a993f..21306570 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -28,6 +28,13 @@ dev = [ "types-requests >= 2.31.0.20240125" ] +docs = [ + "mkdocs==1.5.3", + "mkdocstrings[python]==0.24.0", + "mkdocs-material==9.5.9", + "mike==2.0.0" +] + [tool.setuptools-git-versioning] enabled = true dev_template = "{tag}"