Home

Viewing docs locally

mkdocs serve  # that's it

Deployment

I'll set up mike and document how to use that to deploy docs to github pages.

Quickstart Mkdocs

This is your bible This is just an overview of some features.

print("hello world")

whittle --help  # (1)!

1. Look, an admonation! You can put code in here too!

   print("cool")
   

You can create tabbed blocks which are super useful.

PythoncliDiagram using mermaid

print("hello from tabbed block 1")

print("Hello from highlight")
print("Hello from highlight as well")

whittle --help

graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];

Warning

This is a warning and set to be expanded with !!!

My Tip name

This is a closed tip with ???

To link to internal api docs, use the following.

[LS][whittle.search.local_search]

See LS for more information.

To link to api docs in other codebases, you can directly reference them in much the same way you would import them, for example, this references the ProcessPoolExecutor class in the concurrent.futures module. The backticks are optional, they just make the link look like code.

[`ProcessPoolExecutor`][concurrent.futures.ProcessPoolExecutor]

You can use () like you normally would to link to html links, i.e. Python Docs.

[Python Docs](https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.ProcessPoolExecutor).

You can also link directly to other pages in your repo if you need using a relative syntax,

[API](./contributing)

You can directly include the content of other files if you need, but I've rarely had a use for it. The main one was really for including the CONTIBUTING.md file in the docs/contributing.md file.

This is all that has to be done. The path is relative to the root of the repo (where you execute the command from).

## Contributing

## Installation

```bash
# Create your own fork of the repository if required and replace whittle-org with your username
git clone git@github.com/whittle-org/whittle.git
cd whittle
pip install -e ".[dev]"  # Install what's here (the `.` part) and install the extra dev dependancies

Setup pre-commit to run on every commit

pre-commit install

Testing

pytest

Conventional commits and Commitizen

We use commitizen to manage commits. This enforces conventional commits.

To make a commit, simply run:

cz commit

This will prompt you to enter a commit message and enforce conventional commit formatting.

If you do not use cz commit or make a commit with a conventional commit message, your PR will not pass CI.

Signing commits

Note: we recommend using SSH keys for signing commits for convenience (e.g., you can use the same key for commit signing and for authentication to GitHub).

1. Add a SSH (or GPG) key as a signing key to you GitHub account.
2. Configure git to use the key.

Note: if you don't configure commit signing globally, you will need to use git commit -s/cz commit -s to sign your commits.

<!-- ## Release

Update the version in pyproject.toml first, say to X.Y.Z. If you maintain a changelog, update it.

This part just makes a versioned commit and tag for github and to be able to easily find code at a specific version. It will also help with versioned documentation to have a tag.

git add pyproject.toml [changelog-file-if-any]
git commit -m "bump: X.Y.Z"
git tag X.Y.Z
git push --tags
git push

Then to release on PyPI:

pip install twine # If not already

rm -rf ./dist  # Remove anything currently occupying the dist folder
python -m build --sdist  # Build a source distribution
twine upload dist/*  # Publish to PyPI
``` -->

## Documentation

View locally

```bash
mkdocs --serve

Build and deploy to GitHub Pages. Make sure to specify the github tag you want to deploy.

mike deploy --push --update-aliases <TAG> "latest"

```