diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 34082ba..3435392 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -48,9 +48,11 @@ build-docs:
- python -m pip install --upgrade pip
- pip install -r requirements.txt
- pip install -r requirements-doc.txt
+ - git fetch --unshallow || true # Ensure we have full git history for multiversion
+ - git config --global --add safe.directory $CI_PROJECT_DIR
script:
- cd docs
- - make html
+ - make multiversion
artifacts:
paths:
- docs/build/html/
@@ -58,6 +60,7 @@ build-docs:
only:
- branches
- merge_requests
+ - tags
pages:
stage: pages
@@ -66,6 +69,8 @@ pages:
script:
- mkdir -p public
- cp -r docs/build/html/* public/
+ # Create a redirect from root to latest version
+ - echo '' > public/index.html
artifacts:
paths:
- public
diff --git a/README.md b/README.md
index 4da3d5e..ba500d7 100644
--- a/README.md
+++ b/README.md
@@ -102,7 +102,52 @@ python doi2dataset.py [options] DOI1 DOI2 ...
## Documentation
-Documentation is generated using Sphinx. See the `docs/` directory for detailed API references and usage examples.
+Documentation is generated using Sphinx with multiversion support. See the `docs/` directory for detailed API references and usage examples.
+
+### Building Documentation
+
+The documentation supports multiple versions (branches and tags) and can be built locally or deployed automatically via GitLab CI/CD.
+
+#### Prerequisites
+
+Install documentation dependencies:
+
+```bash
+pip install -r requirements-doc.txt
+```
+
+#### Local Building
+
+```bash
+# Build single version (current branch)
+cd docs
+make html
+
+# Build all versions (multiversion)
+cd docs
+make multiversion
+```
+
+#### Multiversion Configuration
+
+The multiversion setup automatically builds documentation for:
+
+- Main development branches (`main`, `master`, `develop`)
+- Version tags matching the pattern `v*.*.*`
+
+Configuration can be customized in `docs/source/conf.py`:
+
+- `smv_branch_whitelist`: Pattern for included branches
+- `smv_tag_whitelist`: Pattern for included tags
+- `smv_latest_version`: Default version to display
+
+#### Deployment
+
+Documentation is automatically built and deployed via GitLab CI/CD:
+
+- Triggered on pushes to main branches and version tags
+- Deployed to GitLab Pages
+- Accessible at your project's Pages URL
## Testing
diff --git a/docs/Makefile b/docs/Makefile
index d0c3cbf..67dce13 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -12,7 +12,15 @@ BUILDDIR = build
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-.PHONY: help Makefile
+# Multiversion build targets
+multiversion:
+ sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
+multiversion-clean:
+ rm -rf "$(BUILDDIR)/html"
+ sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile multiversion multiversion-clean
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
diff --git a/docs/make.bat b/docs/make.bat
index 747ffb7..f8ee03b 100644
--- a/docs/make.bat
+++ b/docs/make.bat
@@ -25,9 +25,21 @@ if errorlevel 9009 (
if "%1" == "" goto help
+if "%1" == "multiversion" goto multiversion
+if "%1" == "multiversion-clean" goto multiversion-clean
+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
+:multiversion
+sphinx-multiversion %SOURCEDIR% %BUILDDIR%\html %SPHINXOPTS% %O%
+goto end
+
+:multiversion-clean
+rmdir /s /q %BUILDDIR%\html 2>nul
+sphinx-multiversion %SOURCEDIR% %BUILDDIR%\html %SPHINXOPTS% %O%
+goto end
+
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
diff --git a/docs/source/_templates/versions.html b/docs/source/_templates/versions.html
index 237c3fb..77c5b99 100644
--- a/docs/source/_templates/versions.html
+++ b/docs/source/_templates/versions.html
@@ -14,6 +14,25 @@
{%- endfor %}
+ {%- if versiondata.branches %}
+
+ - Branches
+ {%- for branch in versiondata.branches %}
+ -
+ {{ branch.name }}
+
+ {%- endfor %}
+
+ {%- endif %} {%- if versiondata.tags %}
+
+ - Tags
+ {%- for tag in versiondata.tags %}
+ -
+ {{ tag.name }}
+
+ {%- endfor %}
+
+ {%- endif %}
{%- endif %}
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 054ccb0..319dcd0 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -19,7 +19,7 @@ release = '2.0.2'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_multiversion"]
templates_path = ['_templates']
exclude_patterns = []
@@ -42,3 +42,34 @@ suppress_warnings = ['autodoc.import_object', 'ref.duplicate']
html_theme = "sphinx_rtd_theme"
html_static_path = ['_static']
+
+# -- Options for multiversion ------------------------------------------------
+# https://holzhaus.github.io/sphinx-multiversion/master/configuration.html
+
+# Whitelist pattern for tags (only release tags)
+smv_tag_whitelist = r'^v\d+\.\d+(\.\d+)?$'
+
+# Whitelist pattern for branches (main/master and develop)
+smv_branch_whitelist = r'^(main|master|develop)$'
+
+# Whitelist pattern for remotes (origin)
+smv_remote_whitelist = r'^(origin|upstream)$'
+
+# Released versions are branches or tags that match the tag whitelist
+smv_released_pattern = r'^refs/tags/v\d+\.\d+(\.\d+)?$'
+
+# Output directory for multiversion builds
+smv_outputdir_format = '{ref.name}'
+
+# Latest version - check if main exists, fallback to master
+smv_latest_version = 'main'
+
+# Prefer tag over branch if both have the same name
+smv_prefer_remote_refs = False
+
+# Template context for multiversion
+html_context = {
+ 'current_version': os.environ.get('SPHINX_MULTIVERSION_VERSION', 'main'),
+ 'versions': [],
+ 'versiondata': {}
+}
diff --git a/requirements-doc.txt b/requirements-doc.txt
index 045ded0..bb595c3 100644
--- a/requirements-doc.txt
+++ b/requirements-doc.txt
@@ -1,2 +1,3 @@
sphinx>=8.2.3,<9.0.0
sphinx_rtd_theme>=3.0,<4.0
+sphinx-multiversion>=0.2.4