Release v0.1.4: Fix ReadTheDocs documentation build

.readthedocs.yaml

@@ -8,7 +8,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.10"
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.4] - 2025-08-15
+
+### Fixed
+- Fixed ReadTheDocs build issues by simplifying Sphinx configuration
+- Resolved documentation build failures in ReadTheDocs environment
+- Switched to simplified `conf.py` for better compatibility
+- Enhanced ReadTheDocs integration with proper `.readthedocs.yaml` configuration
+
+### Added
+- ReadTheDocs configuration file (`.readthedocs.yaml`) for consistent builds
+- Simplified Sphinx configuration for better RTD compatibility
+
 ## [0.1.3] - 2025-08-15
 
 ### Fixed

docs/conf.py

@@ -1,131 +1,75 @@
 # Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 import os
 import sys
 
-# Mock imports to prevent actual code execution during documentation build
-class MockModule:
-    """Mock module to prevent imports from executing code"""
-    def __getattr__(self, name):
-        return MockModule()
-
-    def __call__(self, *args, **kwargs):
-        return MockModule()
-
-    def __getitem__(self, key):
-        return MockModule()
-
-    def __setitem__(self, key, value):
-        pass
-
-# Mock scientific computing packages that might execute code on import
-MOCK_MODULES = [
-    'numpy', 'pandas', 'xarray', 'matplotlib', 'matplotlib.pyplot',
-    'cartopy', 'cartopy.crs', 'cartopy.feature', 'cmocean', 'cmocean.cm',
-    'cdsapi', 'sklearn', 'sklearn.preprocessing', 'scipy', 'netCDF4',
-    'shapely', 'shapely.geometry', 'metpy', 'metpy.calc', 'metpy.units',
-    'dask', 'dask.array'
-]
-
-for mod_name in MOCK_MODULES:
-    sys.modules[mod_name] = MockModule()
-
-# Add the src directory to the Python path
+# Add the project's source directory to sys.path
 sys.path.insert(0, os.path.abspath('../src'))
 sys.path.insert(0, os.path.abspath('..'))
 
 # -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
 project = 'ATMOS-BUD'
-copyright = '2024, Danilo Couto de Souza'
+copyright = '2025, Danilo Couto de Souza'
 author = 'Danilo Couto de Souza'
-release = '1.0.0'
+release = '0.1.3'
 
 # -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
     'sphinx.ext.intersphinx',
-    'sphinx.ext.autosummary'
 ]
 
 # Napoleon settings
 napoleon_google_docstring = True
 napoleon_numpy_docstring = True
 napoleon_include_init_with_doc = False
 napoleon_include_private_with_doc = False
-napoleon_include_special_with_doc = True
-napoleon_use_admonition_for_examples = False
-napoleon_use_admonition_for_notes = False
-napoleon_use_admonition_for_references = False
-napoleon_use_ivar = False
-napoleon_use_param = True
-napoleon_use_rtype = True
 
 # Autodoc settings
 autodoc_default_options = {
     'members': True,
     'member-order': 'bysource',
-    'special-members': '__init__',
     'undoc-members': True,
     'exclude-members': '__weakref__'
 }
 
-# Prevent autodoc from executing code
-autodoc_mock_imports = MOCK_MODULES
-autodoc_preserve_defaults = True
-
-# Additional safety settings
-autoclass_content = 'class'  # Only include class docstring, not __init__
-autodoc_typehints = 'description'
+# Mock imports for ReadTheDocs
+autodoc_mock_imports = [
+    'numpy', 'pandas', 'xarray', 'matplotlib', 'cartopy', 
+    'cmocean', 'cdsapi', 'scipy', 'netCDF4', 'shapely', 
+    'metpy', 'dask', 'sklearn'
+]
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
-
-
 # -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
 html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
 
-# Theme options for ReadTheDocs
+# Theme options
 html_theme_options = {
     'canonical_url': '',
     'analytics_id': '',
-    'logo_only': False,
     'display_version': True,
     'prev_next_buttons_location': 'bottom',
     'style_external_links': False,
-    'vcs_pageview_mode': '',
-    'style_nav_header_background': '#2980B9',
-    # Toc options
     'collapse_navigation': False,
     'sticky_navigation': True,
     'navigation_depth': 4,
     'includehidden': True,
     'titles_only': False
 }
 
-# Additional HTML options
 html_title = f"ATMOS-BUD v{release} Documentation"
 html_short_title = "ATMOS-BUD Docs"
-html_logo = None
-html_favicon = None
 
-# Links and metadata
-html_context = {
-    "display_github": True,
-    "github_user": "daniloceano",
-    "github_repo": "ATMOS-BUD",
-    "github_version": "main",
-    "conf_py_path": "/docs/",
+# Intersphinx mapping
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'pandas': ('https://pandas.pydata.org/docs/', None),
+    'xarray': ('https://docs.xarray.dev/en/stable/', None),
 }

docs/conf_backup.py

@@ -0,0 +1,131 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+
+# Mock imports to prevent actual code execution during documentation build
+class MockModule:
+    """Mock module to prevent imports from executing code"""
+    def __getattr__(self, name):
+        return MockModule()
+
+    def __call__(self, *args, **kwargs):
+        return MockModule()
+
+    def __getitem__(self, key):
+        return MockModule()
+
+    def __setitem__(self, key, value):
+        pass
+
+# Mock scientific computing packages that might execute code on import
+MOCK_MODULES = [
+    'numpy', 'pandas', 'xarray', 'matplotlib', 'matplotlib.pyplot',
+    'cartopy', 'cartopy.crs', 'cartopy.feature', 'cmocean', 'cmocean.cm',
+    'cdsapi', 'sklearn', 'sklearn.preprocessing', 'scipy', 'netCDF4',
+    'shapely', 'shapely.geometry', 'metpy', 'metpy.calc', 'metpy.units',
+    'dask', 'dask.array'
+]
+
+for mod_name in MOCK_MODULES:
+    sys.modules[mod_name] = MockModule()
+
+# Add the src directory to the Python path
+sys.path.insert(0, os.path.abspath('../src'))
+sys.path.insert(0, os.path.abspath('..'))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'ATMOS-BUD'
+copyright = '2024, Danilo Couto de Souza'
+author = 'Danilo Couto de Souza'
+release = '1.0.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autosummary'
+]
+
+# Napoleon settings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+
+# Autodoc settings
+autodoc_default_options = {
+    'members': True,
+    'member-order': 'bysource',
+    'special-members': '__init__',
+    'undoc-members': True,
+    'exclude-members': '__weakref__'
+}
+
+# Prevent autodoc from executing code
+autodoc_mock_imports = MOCK_MODULES
+autodoc_preserve_defaults = True
+
+# Additional safety settings
+autoclass_content = 'class'  # Only include class docstring, not __init__
+autodoc_typehints = 'description'
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+# Theme options for ReadTheDocs
+html_theme_options = {
+    'canonical_url': '',
+    'analytics_id': '',
+    'logo_only': False,
+    'display_version': True,
+    'prev_next_buttons_location': 'bottom',
+    'style_external_links': False,
+    'vcs_pageview_mode': '',
+    'style_nav_header_background': '#2980B9',
+    # Toc options
+    'collapse_navigation': False,
+    'sticky_navigation': True,
+    'navigation_depth': 4,
+    'includehidden': True,
+    'titles_only': False
+}
+
+# Additional HTML options
+html_title = f"ATMOS-BUD v{release} Documentation"
+html_short_title = "ATMOS-BUD Docs"
+html_logo = None
+html_favicon = None
+
+# Links and metadata
+html_context = {
+    "display_github": True,
+    "github_user": "daniloceano",
+    "github_repo": "ATMOS-BUD",
+    "github_version": "main",
+    "conf_py_path": "/docs/",
+}

docs/conf_simple.py

@@ -0,0 +1,75 @@
+# Configuration file for the Sphinx documentation builder.
+
+import os
+import sys
+
+# Add the project's source directory to sys.path
+sys.path.insert(0, os.path.abspath('../src'))
+sys.path.insert(0, os.path.abspath('..'))
+
+# -- Project information -----------------------------------------------------
+project = 'ATMOS-BUD'
+copyright = '2025, Danilo Couto de Souza'
+author = 'Danilo Couto de Souza'
+release = '0.1.3'
+
+# -- General configuration ---------------------------------------------------
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.intersphinx',
+]
+
+# Napoleon settings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+
+# Autodoc settings
+autodoc_default_options = {
+    'members': True,
+    'member-order': 'bysource',
+    'undoc-members': True,
+    'exclude-members': '__weakref__'
+}
+
+# Mock imports for ReadTheDocs
+autodoc_mock_imports = [
+    'numpy', 'pandas', 'xarray', 'matplotlib', 'cartopy', 
+    'cmocean', 'cdsapi', 'scipy', 'netCDF4', 'shapely', 
+    'metpy', 'dask', 'sklearn'
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+# Theme options
+html_theme_options = {
+    'canonical_url': '',
+    'analytics_id': '',
+    'display_version': True,
+    'prev_next_buttons_location': 'bottom',
+    'style_external_links': False,
+    'collapse_navigation': False,
+    'sticky_navigation': True,
+    'navigation_depth': 4,
+    'includehidden': True,
+    'titles_only': False
+}
+
+html_title = f"ATMOS-BUD v{release} Documentation"
+html_short_title = "ATMOS-BUD Docs"
+
+# Intersphinx mapping
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'pandas': ('https://pandas.pydata.org/docs/', None),
+    'xarray': ('https://docs.xarray.dev/en/stable/', None),
+}

docs/requirements.txt

@@ -1 +1,3 @@
-sphinx==7.2.6
+sphinx==7.2.6
+sphinx-rtd-theme==2.0.0
+docutils<0.19

setup.py

@@ -15,7 +15,7 @@ def read_readme():
 
 setup(
     name='atmos-bud',
-    version='0.1.3',
+    version='0.1.4',
     description='Program for analyzing the heat, vorticity and humidity budgets of limited regions on the atmosphere.',
     long_description=read_readme(),
     long_description_content_type='text/markdown',