fix: docs

Author: DiogoRibeiro7

.github/workflows/sphinx-docs.yaml

@@ -55,7 +55,6 @@ jobs:
         run: |
           mkdir -p "blog-repo/${BLOG_DEST}"
           rsync -av --delete docs/build/ "blog-repo/${BLOG_DEST}/"
-          ls -la "blog-repo/${BLOG_DEST}" | sed -n '1,80p'
 
       - name: Commit and push changes to blog
         run: |

docs/source/conf.py

@@ -1,29 +1,50 @@
 import os
+import sys
 from datetime import datetime
 from importlib import metadata
 
-# Project information
+# Include src directory for autodoc
+sys.path.insert(0, os.path.abspath("../../src"))
+
+# -- Project information -----------------------------------------------------
+
 project = "gen_surv"
 copyright = f"{datetime.now().year}, Diogo Ribeiro"
 author = "Diogo Ribeiro"
-release = metadata.version("gen_surv")
+
+# Get version from installed package metadata
+try:
+    release = metadata.version("gen_surv")
+except metadata.PackageNotFoundError:
+    release = "0.0.0"  # fallback for local builds
 version = release
 
-# General configuration
+# -- General configuration ---------------------------------------------------
+
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosummary",
-    "sphinx.ext.githubpages",
+    "sphinx.ext.githubpages",  # includes .nojekyll
     "myst_parser",
     "sphinx_copybutton",
     "sphinx_design",
     "sphinx_autodoc_typehints",
 ]
 
-# MyST Parser configuration
+autosummary_generate = True
+
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "special-members": "__init__",
+    "undoc-members": True,
+    "exclude-members": "__weakref__",
+}
+
+# MyST Markdown extensions
 myst_enable_extensions = [
     "colon_fence",
     "deflist",
@@ -36,19 +57,6 @@
     "tasklist",
 ]
 
-# Autodoc configuration
-autodoc_default_options = {
-    "members": True,
-    "member-order": "bysource",
-    "special-members": "__init__",
-    "undoc-members": True,
-    "exclude-members": "__weakref__",
-}
-
-# Autosummary
-autosummary_generate = True
-
-# Napoleon settings
 napoleon_google_docstring = True
 napoleon_numpy_docstring = True
 napoleon_include_init_with_doc = False
@@ -61,15 +69,15 @@
     "pandas": ("https://pandas.pydata.org/docs/", None),
 }
 
-# Disable fetching remote inventories when network access is unavailable
+# Disable fetching intersphinx inventories on CI (e.g., for offline builds)
 if os.environ.get("SKIP_INTERSPHINX", "1") == "1":
     intersphinx_mapping = {}
 
-# HTML theme options
+# -- HTML output configuration ----------------------------------------------
+
 html_theme = "sphinx_rtd_theme"
 html_theme_options = {
     "canonical_url": "https://gensurvpy.readthedocs.io/",
-    "analytics_id": "",
     "logo_only": False,
     "prev_next_buttons_location": "bottom",
     "style_external_links": False,
@@ -81,12 +89,19 @@
     "titles_only": False,
 }
 
+# Static assets
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
 
+# Add .nojekyll so GitHub Pages serves _static and other underscored folders
+html_extra_path = [".nojekyll"]
+
+# Required for correct link rendering on GitHub Pages under a subpath
+html_baseurl = "https://diogoribeiro7.github.io/packages/gensurvpy/"
+
 # Output file base name for HTML help builder
 htmlhelp_basename = "gensurvdoc"
 
-# Copy button configuration
+# Copy button config for code blocks
 copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
 copybutton_prompt_is_regexp = True