Use importlib.metadata for package version retrieval in docs (#150)

* Use importlib.metadata for package version retrieval in docs

* cookiecutter template to use import metadata to retrieve the version

* Fixes Requested changes, and preventing logo to overlap texts

* Add v before release in cookiecutter site. Add reference issue for css change

---------

Co-authored-by: sfmig <[email protected]>

Author: richarddushime

docs/requirements.txt

@@ -1,3 +1,4 @@
+-e . # required to build API docs
 linkify-it-py
 myst-parser
 nbsphinx

docs/source/_static/css/custom.css

@@ -11,6 +11,30 @@ html[data-theme=light] {
 body .bd-article-container {
 max-width: 100em !important;
 }
+/* Custom CSS for the documentation site */
+/* prevent logo from being too wide and text clashing with next item */
+/* See https://github.com/pydata/pydata-sphinx-theme/issues/1143#issuecomment-2468763375 */
+
+.navbar-header-items__start .navbar-item {
+  width: 100%;
+}
+
+.navbar-item .navbar-brand {
+  width: 100%;
+}
+
+.navbar-brand img {
+  min-width: 0;
+  height: auto;
+  max-height: 100%;
+  flex-shrink: 1;
+}
+
+.navbar-brand p {
+  flex: 0 1 auto;
+}
+
+/* sponsors */
 
 .col {
 flex: 0 0 50%;

docs/source/conf.py

@@ -1,13 +1,14 @@
 # conf.py
 # Configuration file for the Sphinx documentation builder.
-import setuptools_scm
+from importlib.metadata import version as get_version
 
 
 project = "python-cookiecutter"
 copyright = "2025, University College London"
 author = "Neuroinformatics Unit"
+
 try:
-    full_version = setuptools_scm.get_version(root="../..", relative_to=__file__)
+    full_version = get_version(project)
     # Splitting the release on '+' to remove the commit hash
     release = full_version.split('+', 1)[0]
 except LookupError:
@@ -84,7 +85,7 @@
         },
     ],
     "logo": {
-        "text": f"{project}",
+        "text": f"{project} v{release}",
     },
     "footer_start": ["footer_start"],
     "footer_end": ["footer_end"],

docs/source/contributing.md

@@ -53,6 +53,7 @@ If you are contributing to the Documentation, Before pushing your changes, you c
     the docs:
 
     ``` sh
+     # Must execute from project root directory
     pip install -r docs/requirements.txt
     sphinx-build docs/source docs/build
     ```
@@ -61,7 +62,7 @@ Alternatively, you can use the following commands to install the
 dependencies and build the docs:
 
  ``` sh
-pip install -r docs/requirements.txt
+pip install -r docs/requirements.txt  # Must execute this command from project root directory
 cd docs
 make html
 ```

pyproject.toml

@@ -1,3 +1,22 @@
+[project]
+name = "python-cookiecutter"
+authors = [{ name = "Neuroinformatics Unit" }]
+description = "A tool to automatically create a Python project structure ready to release via GitHub and PyPI."
+readme = "README.md"
+dynamic = ["version"]
+
+license = { text = "BSD-3-Clause" }
+
+[build-system]
+requires = [
+    "setuptools>=64",
+    "wheel",
+    "setuptools-scm[toml]>=8",
+]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+
 [tool.ruff]
 line-length = 79
 exclude = ["__init__.py", "build", ".eggs"]

{{cookiecutter.package_name}}/docs/requirements.txt

@@ -1,3 +1,4 @@
+-e . # required to build API docs
 linkify-it-py
 myst-parser
 nbsphinx

{{cookiecutter.package_name}}/docs/source/conf.py

@@ -9,7 +9,7 @@
 import os
 import sys
 
-import setuptools_scm
+from importlib.metadata import version as get_version
 
 # Used when building API docs, put the dependencies
 # of any class you are documenting here
@@ -24,7 +24,9 @@
 copyright = "2022, {{cookiecutter.full_name}}"
 author = "{{cookiecutter.full_name}}"
 try:
-    release = setuptools_scm.get_version(root="../..", relative_to=__file__)
+    full_version = get_version(project)
+    # Splitting the release on '+' to remove the commit hash
+    release = full_version.split('+', 1)[0]
 except LookupError:
     # if git is not initialised, still allow local build
     # with a dummy version