fix: trigger publish only on release (pyOpenSci#140)

* fix: releaase trigger for publish only

* changlog

* bug: fix documentation setup

* fix:

* fix: sphinx design

Author: lwasser

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 
+* Bug: small bug in the release ci  and update conf.py (@lwasser, #140)
+
+## [v0.6.8]
 * Fix docs CI builds to to simplify maintenance and feedback on jobs (@lwasser, #127, #138)
 
 ## [v0.6.7]

pyproject.toml

@@ -80,7 +80,11 @@ dependencies = [
     "mkdocs-awesome-pages-plugin ~=2.9",
     "pydata_sphinx_theme ~=0.16",
     "myst-parser ~=4.0",
-    "Sphinx ~=8.0",
+    "sphinx ~=8.0",
+    "sphinx-autobuild>=2024.10.3",
+    "sphinx-autoapi>=3.6.0",
+    "sphinx_design>=0.6.1",
+    "sphinx-copybutton",
 ]
 
 [[tool.hatch.envs.test.matrix]]

template/pyproject.toml.jinja

@@ -93,7 +93,7 @@ docs = [
     "pydata-sphinx-theme~=0.16",
     "sphinx-autobuild>=2024.10.3",
     "sphinx-autoapi>=3.6.0",
-    "sphinx-design>=0.6.1",
+    "sphinx_design>=0.6.1",
     "sphinx-copybutton>=0.5.2",
 {%- elif documentation == "mkdocs" %}
     "mkdocs-material ~=9.5",
@@ -323,8 +323,8 @@ build = "mkdocs build {args:--clean --strict}"
 serve = "mkdocs serve {args}"
 {%- endif %}
 {%- if documentation == "sphinx" %}
-build = ["sphinx-apidoc -o docs/api src/{{ package_name}}", "sphinx-build {args:-W -b html docs docs/_build}"]
-serve = ["sphinx-apidoc -o docs/api src/{{ package_name}}", "sphinx-autobuild docs --watch src/{{ package_name }} {args:-b html docs/_build/serve}"]
+build = ["sphinx-build {args:-W -b html docs docs/_build}"]
+serve = ["sphinx-autobuild docs --watch src/{{ package_name }} {args:-b html docs/_build/serve}"]
 {%- endif %}
 {%- endif %}
 

template/{% if documentation == 'sphinx' %}docs{% endif %}/conf.py.jinja

@@ -1,37 +1,56 @@
 #
 # {{ project_name }} documentation build configuration file
 #
+import os
+import sys
 import importlib.metadata
+from datetime import datetime
 
-# -- General configuration -----------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = [
-    "myst_parser",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.autodoc",
-]
+# Ensure src/ is on the path so autodoc can find the package
+sys.path.insert(0, os.path.abspath("../src"))
 
-# The suffix of source filenames.
-source_suffix = ".rst"
-
-# The master toctree document.
-master_doc = "index"
+# Get the year so it automatically updates
+current_year = datetime.now().year
 
+# -- General project information -----------------------------
 # General information about the project.
 project = "{{ project_name }}"
 copyright = "Copyright © {{ year }} {{ copyright_holder }}"
 html_show_sphinx = False
 
-# The version info for the project you're documenting, acts as replacement for
+# Try to get the version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 try:
     version = importlib.metadata.version("{{ package_name }}")
 except importlib.metadata.PackageNotFoundError:
     version = "0.0.0"
 
+# -- General configuration -----------------------------------------------------
+
+# -- General configuration -----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = [
+    "myst_parser",
+    "sphinx_design",
+    "sphinx_copybutton",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon", # Support numpy style docstrings
+    # This allows you to create :::{todo} sections that will not be rendered
+    # in the live docs if you want to leave notes for future work in the docs
+    "sphinx.ext.todo",
+    # Auto generate docs
+    "autoapi.extension",
+]
+
+# Support Markdown source files & rst for api docs
+source_suffix = [".rst", ".md"]
+
+# The master toctree document.
+master_doc = "index"
+
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "default"
 
@@ -44,8 +63,31 @@ language = "en"
 
 # -- Options for extensions ----------------------------------------------------
 # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
-myst_enable_extensions = ["html_image"]
+# -- Options for myst markdown formatting
+myst_enable_extensions = [
+    "html_image",
+    "colon_fence",
+    "deflist",
+    "attrs_inline",
+]
+
+myst_heading_anchors = 3
+myst_footnote_transition = False
+
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+#--------- setup autoapi defaults for your api docs ---------------
 
+# AutoAPI configuration
+autoapi_type = "python"
+# point AutoAPI at your package sources; adjust if using src layout
+autoapi_dirs = ["../src"]
+# Don't let AutoAPI automatically insert a toctree (avoid duplicates)
+autoapi_add_toctree = False
+autoapi_keep_files = False
+autoapi_options = ["members", "undoc-members", "show-inheritance"]
 
 # -- Options for HTML output ---------------------------------------------------
 

template/{% if documentation == 'sphinx' %}docs{% endif %}/index.md.jinja

@@ -8,7 +8,6 @@
 :caption: Contents:
 
 Home <self>
-Documentation <documentation/index>
 :::
 
 This is the landing page of your docs. you can update it as you'd like to.
@@ -42,15 +41,9 @@ If you see syntax like the syntax below, you are looking at rst.
    :caption: Contents:
 ```
 
-[API Documentation](./api/modules.rst)
-
 ## Copyright
 
 {% with license_path = False -%}
 {% include pathjoin("includes", "licenses", "stub.md.jinja") %}
 {%- endwith %}
 
-```{toctree}
-:hidden:
-./api/modules.rst
-```

template/{% if use_git and dev_platform == 'GitHub' %}.github{% endif %}/workflows/release.yml.jinja

@@ -54,8 +54,8 @@ jobs:
   publish:
     name: >-
       Publish Python 🐍 distribution 📦 to PyPI
-    # Modify the repo name below to be your project's repo name.
-    if: github.repository_owner == '{{ username }}'
+    # Only publish to PyPI with a release trigger in your repository.
+    if: github.repository_owner == '{{ username }}' && github.event_name == 'release'
     needs:
       - build
     runs-on: ubuntu-latest

tests/test_template_init.py

@@ -178,7 +178,7 @@ def test_template_suite(
 @pytest.mark.installs
 @pytest.mark.parametrize("use_hatch_envs", [True, False])
 def test_docs_build(documentation: str, generated: Callable[..., Path], use_hatch_envs: bool):
-    """The docs should build."""
+    """The docs should build both with and without hatch environments."""
     if documentation == "no":
         return
 
@@ -193,7 +193,8 @@ def test_docs_build(documentation: str, generated: Callable[..., Path], use_hatc
             pytest.skip(
                 "Dont know enough about invoking shell commands on windows for this :(",
             )
-        run_command("sphinx-apidoc -o docs/api src/alien_clones", project)
+        # With autoapi we shouldn't have to manually run sphinx-apidoc anymore
+        #run_command("sphinx-apidoc -o docs/api src/alien_clones", project)
         # prepend pythonpath so we don't have to actually install here...
         run_command(f"PYTHONPATH={str(project/'src')} sphinx-build -W -b html docs docs/_build", project)