diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index f17bcd7..8624209 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -37,8 +37,6 @@ jobs: uses: pypa/hatch@257e27e51a6a5616ed08a39a408a21c35c9931bc - name: Build the book - env: - SPHINX_GITHUB_CHANGELOG_TOKEN: ${{ github.token }} run: hatch run docs:build - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0 @@ -63,4 +61,4 @@ jobs: uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0 with: github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: build/_build/html + publish_dir: build/html diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..160a872 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,60 @@ +# Migration to Jupyter Book 2.x + +This document describes the migration from Jupyter Book 1.x (Sphinx-based) to Jupyter Book 2.x (MyST-based). + +## What Changed + +### Architecture +- **Jupyter Book 1.x**: Built on Sphinx (Python-based document engine) +- **Jupyter Book 2.x**: Built on MyST Document Engine (JavaScript/TypeScript-based) + +### Configuration Files +- `_config.yml` and `_toc.yml` → consolidated into `myst.yml` +- Old configuration files backed up as `._config.yml.bak` and `._toc.yml.bak` + +### Build Commands +- **Before**: `jupyter-book config sphinx docs && jupyter-book build docs` +- **After**: `jupyter-book build docs` + +### Removed Features + +The following Sphinx-specific features are no longer available in Jupyter Book 2.x: + +1. **sphinx-github-changelog extension**: The automated changelog generation from GitHub releases is not supported. Users should refer to [GitHub Releases](https://github.com/fschuch/wizard-template/releases/) directly. + +2. **Sphinx autodoc**: Automatic API documentation generation from Python docstrings is not available. The API reference has been simplified to point users to the source code. + +3. **Bibliography support (.bib files)**: The `references.bib` file is no longer processed by the build system. + +4. **Custom Sphinx directives**: Some directives like `:link-type:`, `:class-header:`, `:class-container:`, and `:gutter:` options in grids have been removed as they're not supported in MyST. + +5. **RST files**: All reStructuredText (.rst) files have been converted to Markdown (.md) format. + +### What Still Works + +- MyST Markdown syntax (CommonMark + extensions) +- Jupyter notebooks +- Cross-references +- Grid layouts (with simplified options) +- All other MyST-supported directives and roles + +## Benefits of the Migration + +1. **Modern Architecture**: Built on modern JavaScript/TypeScript tooling +2. **Better Performance**: Faster builds with incremental compilation +3. **Improved Web Experience**: Better interactive features and responsive design +4. **Unified Configuration**: Single `myst.yml` file instead of multiple config files +5. **Active Development**: Jupyter Book 2.x is the actively maintained version + +## Known Limitations + +- No Sphinx extension support (including custom plugins) +- Bibliography/citations require different approach +- API documentation needs manual maintenance or alternative tools +- Some advanced Sphinx features not yet available in MyST + +## Further Reading + +- [Jupyter Book 2.x Documentation](https://jupyterbook.org/stable/) +- [MyST Markdown Guide](https://mystmd.org/guide) +- [Upgrade Guide](https://jupyterbook.org/stable/resources/upgrade/) diff --git a/docs/_config.yml b/docs/._config.yml.bak similarity index 100% rename from docs/_config.yml rename to docs/._config.yml.bak diff --git a/docs/_toc.yml b/docs/._toc.yml.bak similarity index 100% rename from docs/_toc.yml rename to docs/._toc.yml.bak diff --git a/docs/intro.md b/docs/intro.md index 1b2825f..36bf6dc 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -1,16 +1,11 @@ # Wizard Template's Documentation -```{centered} _Let the wizard do the heavy lifting so you can focus on your craft_ -``` +_Let the wizard do the heavy lifting so you can focus on your craft_ ::::{grid} 1 1 2 3 -:class-container: text-center -:gutter: 3 :::{grid-item-card} :link: getting-started/about -:link-type: doc -:class-header: bg-light Project Management 🧙🏻‍♂️ ^^^ @@ -21,8 +16,6 @@ This is a general-purpose template that aims to provide a magical start to any P :::{grid-item-card} :link: user-guide/tooling/index -:link-type: doc -:class-header: bg-light Quality Assurance ✅ ^^^ @@ -33,8 +26,6 @@ Use pre-commit hooks, linters, formatters, and unit tests to ensure your code is :::{grid-item-card} :link: user-guide/documentation -:link-type: doc -:class-header: bg-light Documentation 📚 ^^^ @@ -45,8 +36,6 @@ Write documentation with Jupyter Book, including API references, interactive tut :::{grid-item-card} :link: user-guide/versioning-changelog -:link-type: doc -:class-header: bg-light Versioning/Changelog 📜 ^^^ @@ -56,8 +45,6 @@ Commitless versioning and changelog management with git tags, pull request label :::{grid-item-card} :link: user-guide/ci-cd -:link-type: doc -:class-header: bg-light Automated CI/CD 🚀 ^^^ @@ -67,8 +54,6 @@ Test, build, and publish your package to PyPi. Publish documentation to GitHub P :::{grid-item-card} :link: references/further-reading -:link-type: doc -:class-header: bg-light Further Reading 📖 ^^^ @@ -82,4 +67,4 @@ This documentation is organized into a few major sections: - **Getting Started** provides an overview of the project and how to set it up. - **User Guide** contains details on how to use the template and the tools it provides. -- **Reference** section includes further reading, besides [API references](references/api-reference.rst) and [How to Contribute](references/how-to-contribute.md) guides that are ready to be used by any project built with this template. +- **Reference** section includes further reading, besides [API references](references/api-reference.md) and [How to Contribute](references/how-to-contribute.md) guides that are ready to be used by any project built with this template. diff --git a/docs/myst.yml b/docs/myst.yml new file mode 100644 index 0000000..46b488e --- /dev/null +++ b/docs/myst.yml @@ -0,0 +1,42 @@ +version: 1 +project: + title: The Wizard Template for Python Projects + authors: + - name: Felipe N. Schuch + copyright: '2023-2026' + github: fschuch/wizard-template + exports: + - format: pdf + template: plain_latex_book + output: exports/book.pdf + toc: + - file: intro.md + - title: Getting Started + children: + - file: getting-started/about.md + - file: getting-started/dependencies.md + - file: getting-started/use-this-template.md + - title: User Guide + children: + - file: user-guide/tooling/index.md + children: + - file: user-guide/tooling/pre-commit.md + - file: user-guide/tooling/mypy.md + - file: user-guide/tooling/ruff.md + - file: user-guide/tooling/codespell.md + - file: user-guide/tooling/pytest.md + - file: user-guide/tooling/zizmor.md + - file: user-guide/documentation.md + - file: user-guide/versioning-changelog.md + - file: user-guide/ci-cd.md + - title: References + children: + - file: references/further-reading.md + - file: references/api-reference.md + - file: references/how-to-contribute.md + - file: references/what-is-new.md +site: + options: + logo: logo.png + folders: true + template: book-theme diff --git a/docs/references/api-reference.md b/docs/references/api-reference.md new file mode 100644 index 0000000..d45ce76 --- /dev/null +++ b/docs/references/api-reference.md @@ -0,0 +1,11 @@ +# API Reference + +:::{note} +This section provides the API reference for the `wizard_template` package. +::: + +## Core Module + +The core module contains the main functionality of the wizard template. + +For detailed API documentation, please refer to the source code in `src/wizard_template/core.py`. diff --git a/docs/references/api-reference.rst b/docs/references/api-reference.rst deleted file mode 100644 index 1e7f793..0000000 --- a/docs/references/api-reference.rst +++ /dev/null @@ -1,10 +0,0 @@ -API reference -================== - - -Core ----- - -.. automodule:: wizard_template.core - :members: - :show-inheritance: diff --git a/docs/references/what-is-new.md b/docs/references/what-is-new.md index e305625..56fdb1f 100644 --- a/docs/references/what-is-new.md +++ b/docs/references/what-is-new.md @@ -1,10 +1,7 @@ # What's New The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Intended Effort Versioning](https://jacobtomlinson.dev/effver/) (EffVer for short). -Release notes are automatically recovered from GitHub by [sphinx-github-changelog](https://github.com/ewjoachim/sphinx-github-changelog). -```{changelog} -:changelog-url: https://docs.fschuch.com/wizard-template/references/what-is-new.html -:github: https://github.com/fschuch/wizard-template/releases/ -:pypi: https://pypi.org/project/wizard-template/ -``` +:::{note} +Release notes are available on [GitHub Releases](https://github.com/fschuch/wizard-template/releases/) and [PyPI](https://pypi.org/project/wizard-template/). +::: diff --git a/pyproject.toml b/pyproject.toml index b82557b..51ae16d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -33,16 +33,12 @@ tests = [ "pytest>=8.2.2", ] tests-extra = [ - "pytest-randomly==3.16.0", - "pytest-rerunfailures==15.1", + "pytest-randomly==4.0.1", + "pytest-rerunfailures==16.1", "pytest-xdist==3.8.0", ] docs = [ - "docutils==0.21.2", - "jupyter-book==1.0.4.post1", - "sphinx-autobuild==2024.10.3", - "sphinx==7.4.7", - "sphinx-github-changelog==1.7.1", + "jupyter-book==2.1.2", ] [project.urls] @@ -133,9 +129,5 @@ installer = "uv" python = "3.12" [tool.hatch.envs.docs.scripts] -config = "jupyter-book config sphinx docs {args}" -build = ["config", "jupyter-book build docs --path-output build {args}"] -serve = [ - "config", - "sphinx-autobuild docs build/_build/html --open-browser --watch src/wizard_template {args}", -] +build = "jupyter-book build docs --path-output build {args}" +serve = "jupyter-book start docs {args}"