Add-pixi

[jgunstone]

do not merge. for discussion only to see if you like the approach.
If you are happy to proceed then I'll tidy it up some more / I'll probs have some follow up questions.

see #88 and https://jgunstone.github.io/topologicpy/ for example built output

notes.

• rather than trying to build docs from all the existing notebooks I created a new tutorials dir and copied some files over. In a perfect world, I think that these notebooks (or at least a selection of chosen "supported" notebooks) would live in the docs dir and the api docs would be built with qaurtodoc.
• pixi could be also used to simplify some of the code in .github/CI.yml
• ...

[wassimj]

Hi @jgunstone This is very interesting. You are right that the notebooks are going out of date or have errors because of API changes. What I want to do is standardise a version information cell at the top. If you use
from topologicpy.Helper import Helper print(Helper.Version())
It will tell you whether or not you are behind, equal to, or ahead of the published version on PyPi.
Regardless, I love the tutorials idea and how they are presented on quatro.
I am less comfortable with pixi idea simply because I am not familiar with it. I just use anaconda. But didn’t want to force it on those that just want to pip install topologicpy.

[jgunstone]

so pixi doesn't force users to use it.
you can still pip install topologicpy (or pip install . etc) and that will work fine, if you are just a user of topologicpy you probably won't interact with it and will just install it in any way you are most comfortable with (e.g. uv, pip, conda, mamba, poetry, pixi etc.).

the pyproject.toml just adds sections ( [tool.pixi. ) for pixi functionality, and it is expected to be used more in a dev environment.
https://pixi.prefix.dev/latest/python/pyproject_toml/
it is particularly good for configuring dev environments, as they might have multiple environments (e.g. dev, testing, prod) and multiple standards tasks (e.g. run tests, build docs, publish to pypi) etc. that can be templated and standardised so they can be ran locally and then reused and ran in CI.

pixi is built on the conda ecosystem. It was built by the people who made mamba (the fast conda replacement) and can be considered as the next generation of package manager for conda.

For completeness, I think that uv also has some of the same functionality but I'm less familliar with it. I've been working with pixi for the last couple of years and genuinely couldn't recommend it more highly.

[jgunstone]

it can be used in a way as much or as little as you want...
but to try and explain it better, here are a handful of my repos with github CI to: build-docs, test, publish-to-pypi

https://github.com/maxfordham/bdns-plus/tree/main/.github/workflows
https://github.com/maxfordham/pyrulefilter/tree/main/.github/workflows
https://github.com/maxfordham/ipyautoui/tree/main/.github/workflows
https://github.com/maxfordham/netzero-metrics/tree/main/.github/workflows

testing GH actions is difficult and it is much easier to test things locally.
The above GH actions files are basically identical for each repo, but the differences live in the pyproject.toml file which defines the environments and the tasks that must be executed to make those environments.

if I wanted to know how to build the topologicpy docs, then I'd have to check the Github CI:

topologicpy/.github/workflows/build.yml

Lines 43 to 81 in 3c39f7c

	build-docs:
	runs-on: ubuntu-latest
	name: Generate Documentation using Sphinx
	needs: [prepare-build-info]
	steps:
	- uses: actions/checkout@v4
	- name: Set up Python 3.12
	uses: actions/setup-python@v5
	env:
	# Reference: https://github.com/actions/setup-python/issues/862
	# To solve: "A new release of pip is available: ... -> ..."
	PIP_DISABLE_PIP_VERSION_CHECK: 1
	with:
	python-version: '3.12'
	allow-prereleases: true
	cache: pip
	cache-dependency-path: |
	**/pyproject.toml
	**/requirements.txt
	- name: Set project version from git tag/readable name
	run: echo "__version__ = '${{ needs.prepare-build-info.outputs.anyversion }}'" > src/topologicpy/version.py
	- name: Install pandoc
	run: |
	sudo apt install pandoc
	python -m pip install pandoc
	- name: Add sphinx requirements
	run: python -m pip install -r ./docs/requirements.txt
	- name: Build and install optional dependencies (required for use with autodoc of Sphinx)
	run: pip install --verbose ephem torch dgl dglgo scikit-learn
	- name: Build and install the project
	run: pip install --verbose .
	- name: Build docs
	run: cd docs && make html
	- name: Upload artifacts
	uses: actions/upload-artifact@v4
	with:
	name: docs
	path: docs/build/html/
	if-no-files-found: error

and then copy and paste into my console to go through the process locally. with pixi (for any of my repos listed), i'd just run pixi run build-docs and it would configure an environment and run the commands in the right sequence in the correct working dirs for me.

[jgunstone]

hey @wassimj -

I guess I've been unable to convince you to give pixi a go?

one other option would be to use it with a pixi.toml file only, that way the pyproject.toml file wouldn't change and would be kept trad and standard, and the extra pixi functionality is separated out and becomes explicitly opt in for those who want to use it - would this work?

otherwise, it is of course possible to add the quarto tutorials without using pixi at all, we'd just use GH actions to set up the env in a similar way you've done it for the docs.

[wassimj]

one other option would be to use it with a pixi.toml file only, that way the pyproject.toml file wouldn't change and would be kept trad and standard, and the extra pixi functionality is separated out and becomes explicitly opt in for those who want to use it - would this work?

I am happier with this option. Can you send a PR for it? Thanks

[jgunstone]

closing for now so my changes don't trigger this CI