Merge pull request #118 from dnvgl/fix-sphinx-build-with-version

Update documentation

.github/workflows/publish.yml

@@ -57,6 +57,7 @@ jobs:
       env:
         POETRY_PYPI_TOKEN_PYPI : ${{ secrets.PYPI_API_TOKEN }}
     - name: Upload artifacts
+      # https://github.com/actions/upload-artifact#upload-artifact-v3
       uses: actions/upload-artifact@v3
       with:
         name: builds

CHANGELOG.md

@@ -1,4 +1,4 @@
-# Changelog
+# Changelog (deprecated)
 
 > **Note:**
 > After version 4.12.1 this changelog is deprecated. Releases will in future be documented in [Github's releases page](https://github.com/dnvgl/qats/releases). 

docs/source/conf.py

@@ -1,27 +1,39 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
-# qats documentation build configuration file, created by
-# sphinx-quickstart on Sat Dec 16 19:53:09 2017.
-#
-# changes:
-#   02.01.2023/enlo     Updated to use sphinx_rtd_theme.
-#
+# qats documentation build configuration file, 
+# originally created by sphinx-quickstart
 #
+from importlib import metadata
 import os
 import sys
-
+# import the package to be documented
 import qats
 
 # which theme to use
 # options: 'sphinx_rtd_theme' or 'furo'
 THEME = 'furo'  # 'sphinx_rtd_theme'
 
+# determine qats version
+#
+# note: 
+#   As of v5.0.4, qats.__version__ returns "0.0.0" when in a an editable install 
+#   (e.g., if installed from repo using `poetry install` or `pip install -e .`). 
+#   This is, however, exactly the case when documentation is built for readthedocs.
+#   Therefore, qats version must be determined using importlib instead.
+# warning:
+#   importlib.metadata may be tricked if an old folder 'qats.egg-info' is present
+#   (e.g., originating from a previous call to `pip install -e .`). The version
+#   string obtained may then be outdated. However, it is safe to delete this old
+#   folder. Also, this should not be an issue when docs are built by readthedocs.
+__version__ = metadata.version("qats")
+
+
 # print("Generating doc for QATS version {version} installed in {path}"
 #       .format(version=qats.__version__, path=qats.__path__))
 print("Generating doc for QATS version {version} installed in {path},\n"
       "... using Sphinx theme '{theme}'"
-      .format(version=qats.__version__, path=qats.__path__, theme=THEME))
+      .format(version=__version__, path=qats.__path__, theme=THEME))
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -74,7 +86,7 @@
 # release: the full version, including alpha/beta/rc tags.
 # version = ''
 # release = ''
-version = qats.__version__
+version = __version__
 release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation

docs/source/index.rst

@@ -49,7 +49,13 @@ inspecting, quality assurance and reporting. Use the library for more advanced o
 Python version support
 **********************
 
-QATS currently supports Python version 3.8 and later. Note that version 3.12 is not properly tested but should work.
+.. QATS currently supports Python version 3.8 and later. Note that version 3.12 is not properly tested but should work.
+
+QATS currently supports Python version 3.8+. 
+
+.. note::
+    Python version <=3.11 is recommended, as version 3.12 is not yet formally tested.
+
 
 
 
@@ -63,7 +69,11 @@ The `source code <https://github.com/dnvgl/qats>`_, `issue tracker <https://gith
 Downloads
 *********
 
-You can download and install QATS from `PyPI <https://pypi.org/project/qats/>`_.
+.. You can download and install QATS from `PyPI <https://pypi.org/project/qats/>`_. 
+.. Or, see the :ref:`getting_started` for installation instructions.
+
+QATS may be downloaded from `PyPI/qats <https://pypi.org/project/qats/>`_. 
+See the :ref:`getting_started` section for installation instructions.
 
 Table of contents
 *****************
@@ -97,3 +107,4 @@ Table of contents
    PyPI Project <https://pypi.org/project/qats/>
    GitHub Repository <https://github.com/dnvgl/qats>
    Issue Tracker <https://github.com/dnvgl/qats/issues>
+   Changelog <https://github.com/dnvgl/qats/releases>

pyproject.toml

@@ -12,11 +12,13 @@ include = [
     "LICENSE",
     "CHANGELOG.md"
 ]
+# some urls given here instead of ulrs section (affects listed order on PyPi)
+homepage = "https://github.com/dnvgl/qats"
+repository = "https://github.com/dnvgl/qats"
+documentation = "https://qats.readthedocs.io"
 
 [tool.poetry.urls]
-Homepage = "https://github.com/dnvgl/qats"
-Source = "https://github.com/dnvgl/qats"
-Documentation = "https://qats.readthedocs.io"
+# additional urls not listed under tool.poetry
 Download = "https://pypi.org/project/qats/"
 Issues = "https://github.com/dnvgl/qats/issues"
 Changelog = "https://github.com/dnvgl/qats/releases"