bug: ensure sphinx build works as expected (pyOpenSci#130)

* bug: ensure sphinx build works

* add: changelog

* fix: cleanup include

* fix: versions

Author: lwasser

CHANGELOG.md

@@ -1,5 +1,12 @@
 # pyOpenSci packaging template Changelog
 
 ## [Unreleased]
+* Fix RTD build for sphinx and move to optional.dependencies for docs (@lwasser, #126)
+
+## [0.6.0]
+
+### Added
 
 * Update release workflow to follow PyPA / PyPI recommended practices (@lwasser, #48)
+* development instructions for hatch envt by @lwasser in #115
+* uv by @lwasser in #116

DEVELOPMENT.md

@@ -1,14 +1,14 @@
 # Development Guide
 
-If you are working on development locally and on the main branch, you can run the template
-using the following command:
+If you are working on development locally and on the main branch, you can run
+the template using the following command:
 
 `copier copy .  dirnam_here`
 
 If you have made local changes to the template, you will see a warning
 telling you that the template's current version control state is "dirty".
-This means that you have changed things and they aren't committed  to
-version control, yet.
+This means that you have changed things and they aren't committed to
+version control yet.
 
 ```console
 /your/path/python3.12/site-packages/copier/vcs.py:201: DirtyLocalWarning: Dirty template changes included automatically.

README.md

@@ -123,9 +123,17 @@ Copying from template version 0.6.4.1
 ```
 
 Once you have created your package, you can install it in editable mode using
-pip.
+pip or uv.
 
-First, CD to the directory where your new package lives and install the package in editable mode:
+### For UV users
+```console
+$ cd my_directory
+$ uv sync # Run uv sync to create a venv and install your dependencies
+$ UV run python # Open a python prompt using the UV managed environment
+
+### For pip users
+
+First, CD to the directory where your new package lives, and install the package in editable mode:
 
 ```console
 $ cd my_directory

includes/pyproject/deps-pep-621.toml.jinja

@@ -1,17 +1,3 @@
-{% if documentation == "mkdocs" -%}
-docs = [
-    "mkdocs-material ~=9.5",
-    "mkdocstrings[python] ~=0.24",
-    "mkdocs-awesome-pages-plugin ~=2.9",
-]
-{% elif documentation == "sphinx" -%}
-docs = [
-    "pydata_sphinx_theme ~=0.16",
-    "myst-parser ~=4.0",
-    "Sphinx ~=8.0",
-    "sphinx-autobuild ==2024.10.3"
-]
-{% endif %}
 {%- if use_test -%}
 tests = [
     "pytest",

template/pyproject.toml.jinja

@@ -82,6 +82,23 @@ dev = [
     audit]",
     {%- endif %}
 ]
+
+docs = [
+{%- if documentation == "sphinx" %}
+    "sphinx~=8.0",
+    "myst-parser>=4.0",
+    "pydata-sphinx-theme~=0.16",
+    "sphinx-autobuild>=2024.10.3",
+    "sphinx-autoapi>=3.6.0",
+    "sphinx-design>=0.6.1",
+    "sphinx-copybutton>=0.5.2",
+{%- elif documentation == "mkdocs" %}
+    "mkdocs-material ~=9.5",
+    "mkdocstrings[python] ~=0.24",
+    "mkdocs-awesome-pages-plugin ~=2.9",
+{% endif %}
+]
+
 {%- if not use_hatch_envs %}
 {% include pathjoin('includes', 'pyproject', 'deps-pep-621.toml.jinja') %}
 {%- endif %}
@@ -271,21 +288,10 @@ run = "pytest {args:--cov={{ package_name }} --cov-report=term-missing}"
 # This sets up a hatch environment with associated dependencies that need to be installed
 [tool.hatch.envs.docs]
 description = """Build or serve the documentation."""
-{%- if documentation == "mkdocs" %}
-extra-dependencies = [
-    "mkdocs-material ~=9.5",
-    "mkdocstrings[python] ~=0.24",
-    "mkdocs-awesome-pages-plugin ~=2.9",
-]
-{%- elif documentation == "sphinx" %}
-python = "3.10"
-dependencies = [
-    "pydata_sphinx_theme ~=0.16",
-    "myst-parser ~=4.0",
-    "Sphinx ~=8.0",
-    "sphinx-autobuild ==2024.10.3"
+# Install optional dependency test for docs
+features = [
+    "docs",
 ]
-{%- endif %}
 
 # This table contains the scripts that you can use to build and serve your docs
 # hatch run docs:build will build your documentation

template/{% if documentation == 'sphinx' %}docs{% endif %}/_static/.gitkeep

@@ -7,13 +7,14 @@ build:
   tools:
     python: "3.12"
   commands:
-    - pip install --upgrade pip setuptools wheel
-    - pip install hatch
-{%- if documentation == "mkdocs" %}
+    - pip install --upgrade pip
+    - pip install -e '.[docs]'
+{%- if documentation == "sphinx" %}
+    # Make sure RTD can find the html output
+    - sphinx-build -b html docs $READTHEDOCS_OUTPUT/html
+{%- elif documentation == "mkdocs" %}
     - hatch run docs:build -- --strict --site-dir "${READTHEDOCS_OUTPUT}/html"
 
 mkdocs:
   configuration: mkdocs.yml
-{%- elif documentation == "sphinx" %}
-    - hatch run docs:build
 {%- endif %}