updates to docs and packaging

.readthedocs.yaml

@@ -1,9 +1,42 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
 version: 2
 
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - htmlzip
+  - pdf
+
 build:
   os: ubuntu-22.04
   tools:
     python: mambaforge-4.10
+  jobs:
+    post_checkout:
+      - git fetch --unshallow || true
+      - git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*' || true
+      - git fetch --all --tags || true
+    pre_install:
+      - git update-index --assume-unchanged docs/readthedocs.yaml docs/conf.py
+    post_install:
+      - towncrier build --keep
 
 conda:
-  environment: docs/rtd_environment.yaml
+  environment: docs/readthedocs.yaml
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

cookiecutter.json

@@ -17,7 +17,7 @@
         "3.13"
     ],
     "use_compiled_extensions": "n",
-    "enable_dynamic_dev_versions": "n",
+    "enable_dynamic_dev_versions": "y",
     "include_example_code": "n",
     "include_github_workflows": "y",
     "_sphinx_theme": "alabaster",

{{ cookiecutter.package_name }}/_dev/__init__.py

@@ -0,0 +1,6 @@
+"""
+This package contains utilities that are only used when developing drms in a
+copy of the source repository.
+These files are not installed, and should not be assumed to exist at
+runtime.
+"""

{{ cookiecutter.package_name }}/_dev/scm_version.py

@@ -0,0 +1,13 @@
+# Try to use setuptools_scm to get the current version; this is only used
+# in development installations from the git repository.
+import os.path
+
+try:
+    from setuptools_scm import get_version
+
+    version = get_version(root=os.path.join('..', '..'), relative_to=__file__)
+except ImportError:
+    raise
+except Exception as e:
+    raise ValueError('setuptools_scm can not determine version.') from e
+

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

@@ -5,18 +5,62 @@
 # http://www.sphinx-doc.org/en/master/config
 
 import datetime
+import importlib
+import sys
+import os
+from pathlib import Path
+
+if sys.version_info < (3, 11):
+     import tomli as tomllib
+else:
+     import tomllib
+
+from packaging.version import Version
+from configparser import ConfigParser
+
+import sphinx
+
+from sphinx.ext.autodoc import AttributeDocumenter
 
 # -- Project information -----------------------------------------------------
 
 # The full version, including alpha/beta/rc tags
 from {{ cookiecutter.module_name }} import __version__
 
-release = __version__
+# 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.
+#
+# The short X.Y version.
+package = importlib.import_module(metadata['name'])
+try:
+    version = package.__version__.split('-', 1)[0]
+
+    # The full version, including alpha/beta/rc tags.
+    release = package.__version__
+
+except AttributeError:
+    version = 'dev'
+    release = 'dev'
+
+
+# after you've used the package template, you can switch to these lines
+# to populate metadata from the pyproject.toml file so that changes are picked 
+# up for things in the project section of the toml
+with open(Path(__file__).parent.parent / "pyproject.toml", "rb") as metadata_file:
+    metadata = tomllib.load(metadata_file)['project']
+
+# If your documentation needs a minimal Sphinx version, state it here.
+# needs_sphinx = '1.3'
+
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
 
 project = "{{ cookiecutter.package_name }}"
 author = "{{ cookiecutter.author_name }}"
 copyright = f"{datetime.datetime.now().year}, {author}"  # noqa: A001
 
+
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -57,7 +101,10 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"python": ("https://docs.python.org/", None)}
+intersphinx_mapping = {"python": ("https://docs.python.org/", None),
+                       'numpy': ('https://numpy.org/devdocs', None),
+                       'scipy': ('http://scipy.github.io/devdocs', None),
+                       'matplotlib': ('http://matplotlib.org/', None),}
 
 # -- Options for HTML output -------------------------------------------------
 

{{ cookiecutter.package_name }}/pyproject.toml

@@ -43,6 +43,11 @@ test = [
 docs = [
     "sphinx",
     "sphinx-automodapi",
+    "matplotlib",
+    "sphinx",
+    "sphinx-automodapi",
+    "tomli; python_version <\"3.11\"",
+    "tomllib; python_version >\"3.11\"",
 ]
 
 {%- if cookiecutter.project_url %}