Sphinx support

[samimia-swks]

From my research it seems like sphinx still carries significant advantages over Mkdocs (despite its higher complexity), namely a much better automatic API documentation. Some of the best new project docs I have looked at use sphinx with this theme: https://pradyunsg.me/furo/reference/api/
And major projects like numpy / scipy use sphinx.

[kolumdium]

I tried it out and you can do this yourself after init with the cutter.
Given that Sphinx needs a bit more manuel setup anyway the save of adding it to the cutter is probably minimal.
I prefer sphinx too but also basedpyright over mypy. If you want to make those changes you can always fork it.

Here is how i did the setup after the init.

uv remove mkdocs
uv add sphinx

.github/workflows/main.yml

      - name: Check if documentation can be built
        run: uv run mkdocs build -s # replace this with
        run: uv run sphinx-build -W -b html docs docs/_build/html

on-release-main.yaml

      - name: Deploy documentation #replace this
        run: uv run mkdocs gh-deploy --force #replace this
      - name: Build documentation
        run: uv run sphinx-build -b html docs docs/_build/html

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/_build/html

add this to .gitignore

docs/_build/

you can change the makefile

.PHONY: docs-test
docs-test: ## Test if documentation can be built without warnings or errors
	@uv run mkdocs build -s  #replace this
	@uv run sphinx-build -W -b html docs docs/_build/html

.PHONY: docs
docs: ## Build and serve the documentation
	@uv run mkdocs serve  #replace this
	@uv run sphinx-autobuild docs docs/_build/html

Then just add a normal docs/conf.py for sphinx
and your index.rst and modules.rst