From 4e2414c8fea52ca3137780078aa7ea8790f0b07b Mon Sep 17 00:00:00 2001 From: Megan Sosey Date: Mon, 25 Nov 2024 08:53:46 -0500 Subject: [PATCH] updates to docs and packaging --- .readthedocs.yaml | 35 ++++++++++++- cookiecutter.json | 2 +- .../_dev/__init__.py | 6 +++ .../_dev/scm_version.py | 13 +++++ {{ cookiecutter.package_name }}/docs/conf.py | 51 ++++++++++++++++++- .../pyproject.toml | 5 ++ 6 files changed, 108 insertions(+), 4 deletions(-) create mode 100644 {{ cookiecutter.package_name }}/_dev/__init__.py create mode 100644 {{ cookiecutter.package_name }}/_dev/scm_version.py diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 0af9847..1f51e7d 100644 --- a/.readthedocs.yaml +++ b/.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 \ No newline at end of file diff --git a/cookiecutter.json b/cookiecutter.json index eedf9fd..c7ca46d 100644 --- a/cookiecutter.json +++ b/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", diff --git a/{{ cookiecutter.package_name }}/_dev/__init__.py b/{{ cookiecutter.package_name }}/_dev/__init__.py new file mode 100644 index 0000000..72583c0 --- /dev/null +++ b/{{ 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. +""" diff --git a/{{ cookiecutter.package_name }}/_dev/scm_version.py b/{{ cookiecutter.package_name }}/_dev/scm_version.py new file mode 100644 index 0000000..a3516a4 --- /dev/null +++ b/{{ 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 + diff --git a/{{ cookiecutter.package_name }}/docs/conf.py b/{{ cookiecutter.package_name }}/docs/conf.py index 2deebc5..c99f14f 100644 --- a/{{ cookiecutter.package_name }}/docs/conf.py +++ b/{{ 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 ------------------------------------------------- diff --git a/{{ cookiecutter.package_name }}/pyproject.toml b/{{ cookiecutter.package_name }}/pyproject.toml index 317cef5..1748667 100644 --- a/{{ cookiecutter.package_name }}/pyproject.toml +++ b/{{ 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 %}