Add multiversion documentation support

Enable multiversion documentation generation with: - Updated GitLab CI configuration - Added
multiversion build targets - Configured multiversion settings - Updated documentation and templates
- Added sphinx-multiversion dependency

.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 '<meta http-equiv="refresh" content="0; url=./main/">' > public/index.html
   artifacts:
     paths:
       - public

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
 

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).

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%
 

docs/source/_templates/versions.html

@@ -14,6 +14,25 @@
             </dd>
             {%- endfor %}
         </dl>
+        {%- if versiondata.branches %}
+        <dl>
+            <dt>Branches</dt>
+            {%- for branch in versiondata.branches %}
+            <dd>
+                <a href="{{ branch.url }}">{{ branch.name }}</a>
+            </dd>
+            {%- endfor %}
+        </dl>
+        {%- endif %} {%- if versiondata.tags %}
+        <dl>
+            <dt>Tags</dt>
+            {%- for tag in versiondata.tags %}
+            <dd>
+                <a href="{{ tag.url }}">{{ tag.name }}</a>
+            </dd>
+            {%- endfor %}
+        </dl>
+        {%- endif %}
     </div>
 </div>
 {%- endif %}

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': {}
+}

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