Update documentation build process for multiversion support

.gitlab-ci.yml

@@ -55,7 +55,7 @@ build-docs:
     - make multiversion
   artifacts:
     paths:
-      - docs/build/html/
+      - docs/build/multiversion/html/
     expire_in: 1 week
   only:
     - branches
@@ -68,7 +68,7 @@ pages:
     - build-docs
   script:
     - mkdir -p public
-    - cp -r docs/build/html/* public/
+    - cp -r docs/build/multiversion/html/* public/
     # Create a redirect from root to latest version
     - echo '<meta http-equiv="refresh" content="0; url=./main/">' > public/index.html
   artifacts:

docs/Makefile

@@ -7,20 +7,38 @@ SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
+MULTIVERSIONDIR = build/multiversion
 
 # Put it first so that "make" without argument is like "make help".
 help:
+	@echo "Sphinx documentation build commands:"
+	@echo ""
+	@echo "Single-version builds (output: build/html/):"
+	@echo "  html       Build HTML documentation for current version"
+	@echo "  clean      Clean single-version build directory"
+	@echo ""
+	@echo "Multiversion builds (output: build/multiversion/html/):"
+	@echo "  multiversion       Build multiversion HTML documentation"
+	@echo "  multiversion-clean Clean and rebuild multiversion documentation"
+	@echo ""
+	@echo "Utility commands:"
+	@echo "  clean-all  Clean both single and multiversion build directories"
+	@echo ""
+	@echo "Standard Sphinx help:"
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 # Multiversion build targets
 multiversion:
-	sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+	sphinx-multiversion "$(SOURCEDIR)" "$(MULTIVERSIONDIR)/html" $(SPHINXOPTS) $(O)
 
 multiversion-clean:
-	rm -rf "$(BUILDDIR)/html"
+	rm -rf "$(MULTIVERSIONDIR)/html"
-	sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+	sphinx-multiversion "$(SOURCEDIR)" "$(MULTIVERSIONDIR)/html" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile multiversion multiversion-clean
+clean-all:
+	rm -rf "$(BUILDDIR)" "$(MULTIVERSIONDIR)"
+
+.PHONY: help Makefile multiversion multiversion-clean clean-all
 
 # 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

@@ -32,12 +32,12 @@ if "%1" == "multiversion-clean" goto multiversion-clean
 goto end
 
 :multiversion
-sphinx-multiversion %SOURCEDIR% %BUILDDIR%\html %SPHINXOPTS% %O%
+sphinx-multiversion %SOURCEDIR% %BUILDDIR%\multiversion\html %SPHINXOPTS% %O%
 goto end
 
 :multiversion-clean
 rmdir /s /q %BUILDDIR%\html 2>nul
-sphinx-multiversion %SOURCEDIR% %BUILDDIR%\html %SPHINXOPTS% %O%
+sphinx-multiversion %SOURCEDIR% %BUILDDIR%\multiversion\html %SPHINXOPTS% %O%
 goto end
 
 :help

docs/source/_templates/versions.html

@@ -2,7 +2,7 @@
 <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
     <span class="rst-current-version" data-toggle="rst-current-version">
         <span class="fa fa-book"> Read the Docs</span>
-        v: {{ current_version }}
+        v: {{ current_version.name.lstrip('v') }}
         <span class="fa fa-caret-down"></span>
     </span>
     <div class="rst-other-versions">

docs/source/conf.py

@@ -61,6 +61,9 @@ smv_released_pattern = r'^refs/tags/v\d+\.\d+(\.\d+)?$'
 # Output directory for multiversion builds
 smv_outputdir_format = '{ref.name}'
 
+# Root output directory for multiversion (will be build/multiversion/html)
+smv_root_path = '../build/multiversion/html'
+
 # Latest version - check if main exists, fallback to master
 smv_latest_version = 'main'
 

docs/source/contributing.rst

@@ -0,0 +1,141 @@
+Contributing
+============
+
+We welcome contributions to **doi2dataset**! This guide provides information for developers who want to contribute to the project or build the documentation locally.
+
+Building Documentation
+----------------------
+
+The documentation is built using Sphinx with multiversion support, allowing for documentation of multiple versions (branches and tags) simultaneously.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+Before building the documentation, install the documentation dependencies:
+
+.. code-block:: bash
+
+   pip install -r requirements-doc.txt
+
+Local Building
+~~~~~~~~~~~~~~
+
+Single Version (Current Branch)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To build documentation for the current branch only:
+
+.. code-block:: bash
+
+   cd docs
+   make html
+
+The generated documentation will be available in ``docs/build/html/``.
+
+Multiversion Documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To build documentation for all versions (branches and tags):
+
+.. code-block:: bash
+
+   cd docs
+   make multiversion
+
+This will build documentation for:
+
+- Main development branches (``main``, ``master``, ``develop``)
+- Version tags matching the pattern ``v*.*.*``
+
+Multiversion Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The multiversion setup 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
+
+The generated documentation will be available in ``docs/build/multiversion/html/``.
+
+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
+-------
+
+Tests are implemented with pytest and provide comprehensive coverage of core functionalities.
+
+Running Tests
+~~~~~~~~~~~~~
+
+To run the test suite:
+
+.. code-block:: bash
+
+   pytest
+
+Or using the Python module syntax:
+
+.. code-block:: bash
+
+   python -m pytest
+
+Code Coverage
+~~~~~~~~~~~~~
+
+The project includes code coverage analysis using pytest-cov. To run tests with coverage:
+
+.. code-block:: bash
+
+   pytest --cov=.
+
+Generate a detailed HTML coverage report:
+
+.. code-block:: bash
+
+   pytest --cov=. --cov-report=html
+
+This creates a ``htmlcov`` directory. Open ``htmlcov/index.html`` in a browser to view the detailed coverage report.
+
+Development Setup
+-----------------
+
+1. Fork the repository
+2. Clone your fork locally
+3. Install development dependencies:
+
+   .. code-block:: bash
+
+      pip install -r requirements-dev.txt
+
+4. Make your changes
+5. Run tests to ensure everything works
+6. Submit a pull request
+
+Code Style
+----------
+
+Please follow the existing code style and conventions used in the project. Make sure to:
+
+- Write clear, descriptive commit messages
+- Add tests for new functionality
+- Update documentation as needed
+- Follow Python best practices
+
+Submitting Changes
+------------------
+
+1. Create a new branch for your feature or bug fix
+2. Make your changes with appropriate tests
+3. Ensure all tests pass
+4. Update documentation if needed
+5. Submit a pull request with a clear description of your changes
+
+Thank you for contributing to **doi2dataset**!

docs/source/index.rst

@@ -38,4 +38,5 @@ Key Features:
    installation
    usage
    modules
+   contributing
    faq

docs/source/installation.rst

@@ -9,7 +9,7 @@ Clone the repository from GitHub by running the following commands in your termi
 
 .. code-block:: bash
 
-   git clone https://github.com/your_username/doi2dataset.git
+   git clone https://git.uni-due.de/cbm343e/doi2dataset.git
    cd doi2dataset
 
 Using pip (if available)