Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Installation instructions buff #129

Merged
merged 3 commits into from
Aug 4, 2024
Merged

Installation instructions buff #129

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6ea45ef
Add sphinx-tabs as dependency
ekiefl Aug 4, 2024
044fec6
Streamline installation instruction formatting
ekiefl Aug 4, 2024
d504039
Small changes
ekiefl Aug 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Pooltool needs and welcomes people of all skill levels who are excited about thi
Contributions to pooltool are made via GitHub. To get started:

1. Fork the repo and create your branch from `main`.
1. Install pooltool using the "developer" instructions [here](https://pooltool.readthedocs.io/en/latest/getting_started/install.html).
1. Install pooltool using the "install from source" instructions [here](https://pooltool.readthedocs.io/en/latest/getting_started/install.html).
1. If you've added code that should be tested, add tests.
1. If you've changed [the API](https://pooltool.readthedocs.io/en/latest/autoapi/index.html), update the documentation.
1. Create a pull request (PR), ensuring you have a clear description of the problem you're solving and the solution.
Expand Down
5 changes: 5 additions & 0 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
import os
import sys

sys.path.insert(0, os.path.abspath("./"))
sys.path.insert(0, os.path.abspath("../"))

# -- Project information -----------------------------------------------------
Expand All @@ -30,6 +31,7 @@
"sphinx.ext.napoleon",
"sphinx.ext.mathjax",
"sphinx_copybutton",
"sphinx_tabs.tabs",
"autoapi.extension",
"sphinx.ext.viewcode",
"sphinx.ext.intersphinx",
Expand Down Expand Up @@ -85,6 +87,9 @@
"numba": ("https://numba.readthedocs.io/en/stable/", None),
}

# -- sphinx-tabs options
sphinx_tabs_disable_tab_closing = True

# -- copybutton options
copybutton_exclude = ".linenos, .gp, .go"

Expand Down
80 changes: 34 additions & 46 deletions docs/getting_started/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,66 +1,56 @@
# Installation

You're just a few seconds away from exploring the interactive interface.
Pooltool is available on Linux, Mac, and Windows for the following Python versions:

```{figure} ../_assets/gallery_6.jpg
---
height: 300px
---
```
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pooltool-billiards)

```{figure} ../_assets/gallery_7.jpg
---
height: 300px
---
```
## Using pip

## Requirements
Pooltool is hosted on the [Python Package Index (PyPI)](https://pypi.org/project/pooltool-billiards/) and can be installed with pip.

Pooltool is compatible with Python >=3.9,<3.13.
```{eval-rst}
.. tabs::

## Install option (1): pip
.. tab:: **Linux**

| GUI | API | Develop |
|-----|-----|---------|
| ✅ | ✅ | ❌ |
.. code-block:: bash

<details><summary style="font-style: italic;">[Click to expand/collapse]</summary>
pip install pooltool-billiards --extra-index-url https://archive.panda3d.org/

### MacOS
(*Providing the Panda3D archive is required until Panda3D v1.11 is released*)

```python
pip install pooltool-billiards
```
.. tab:: **MacOS**

### Linux & Windows
.. code-block:: bash

```python
pip install pooltool-billiards --extra-index-url https://archive.panda3d.org/
```
pip install pooltool-billiards

</details>
.. tab:: **Windows**

## Install option (2): developer
.. code-block:: bash

| GUI | API | Develop |
|-----|-----|---------|
| ✅ | ✅ | ✅ |
pip install pooltool-billiards --extra-index-url https://archive.panda3d.org/

<details><summary style="font-style: italic;">[Click to expand/collapse]</summary>
(*Providing the Panda3D archive is required until Panda3D v1.11 is released*)
```

## From source

If you want to develop for pooltool, have access to the most up-to-date version of the codebase, or modify the code to your liking, this is for you.

<details><summary style="font-style: italic;">[Click to expand/collapse]</summary>

A small note. If you don't have the ability to create isolated python environments, I would recommend installing `conda` ([here](https://conda.io/projects/conda/en/latest/user-guide/install/index.html)) so you can isolate pooltool from your other business.

**(i)** Grab a copy of the codebase.
**1.** Grab a copy of the codebase.

```bash
cd <A_DIRECTORY_YOU_LIKE>
git clone https://github.com/ekiefl/pooltool.git
cd pooltool
```

**(ii)** Create a new python environment that uses Python 3.12.4.
**2.** Create a new python environment that uses Python 3.12.4.

If you have `conda`, just run this:

Expand All @@ -73,15 +63,14 @@ Regardless of how you managed your python environment, please verify you're runn

```bash
$ python
Python 3.8.10 (default, May 19 2021, 11:01:55)
[Clang 10.0.0 ] :: Anaconda, Inc. on darwin
Python 3.12.4 | packaged by Anaconda, Inc. | (main, Jun 18 2024, 10:14:12) [Clang 14.0.6 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> exit()
```

**(iii)** Install poetry, a popular python package/environment manager.
**3.** Install poetry, a popular python package/environment manager.

If you created your environment with conda, you've already installed poetry.
If you created your environment with conda (_e.g._ `conda env create -f environment.yml`), poetry is already part of your `pooltool-dev` environment.

Otherwise, install with

Expand All @@ -96,22 +85,22 @@ $ poetry --version
Poetry (version 1.8.3)
```

**(iv)** Install pooltool.
**4.** Install pooltool.

```bash
poetry install
pip install -e .
```

**(v)** install the pre-commit hooks:
**5.** install the pre-commit hooks:

This will automatically format your code according to the pooltool standard whenever you commit.
If you plan on contributing to pooltool, install the pre-commit hooks. They will automatically format your code according to the pooltool standard whenever you commit.

```
pre-commit install
```

**(vi)** test out your installation:
**6.** test out your installation:

```bash
run-pooltool
Expand All @@ -121,15 +110,14 @@ The game window should appear (escape key to exit).

</details>

## Next
## Test

Test your installation by printing the version:

```bash
$ python -c "import pooltool; print(pooltool.__version__)"
0.4.0
python -c "import pooltool; print(pooltool.__version__)"
```

(If you installed via the developer instructions, the output should be `0.0.0`)
If installed from source, output should be `0.0.0`.

Next, it's time to learn about the interface.
22 changes: 21 additions & 1 deletion poetry.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ sphinx-copybutton = ">=0.5.2"
furo = ">=2024.5.6"
myst-parser = ">=3.0.1"
sphinx-autoapi = ">=3.1.2"
sphinx-tabs = ">=3.4.5"

[tool.ruff]
line-length = 88
Expand Down
Loading