📝 Fix Documentation Build on ReadTheDocs And Add Documentation About …

…Versioning (#673)
bo4e · Dec 27, 2023 · 2ace752 · 2ace752
1 parent ddcba8f
commit 2ace752
Show file tree

Hide file tree

Showing 4 changed files with 42 additions and 4 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -24,6 +24,9 @@
 sys.path.insert(0, os.path.join(__location__, "../docs"))
 from uml import PlantUMLNetwork, build_network, compile_files_kroki, write_class_umls
 
+# import package bo4e to clarify namespaces and prevent circular import errors
+from bo4e import *
+
 # -- Run sphinx-apidoc ------------------------------------------------------
 # This hack is necessary since RTD does not issue `sphinx-apidoc` before running
 # `sphinx-build -b html . _build/html`. See Issue:

diff --git a/docs/index.rst b/docs/index.rst
@@ -1,8 +1,9 @@
 =============
-bo4e
+BO4E
 =============
 
-This is the documentation of **bo4e** python package.
+This is the official documentation of **BO4E** datamodel.
+Cause of the fact that the datamodel is written in Python, it is also the Python documentation.
 
 
 Contents
@@ -13,6 +14,7 @@ Contents
 
    License <license>
    Authors <authors>
+   Versioning <versioning>
    Changelog <changelog>
    Module Reference <api/modules>
 

diff --git a/docs/versioning.rst b/docs/versioning.rst
@@ -0,0 +1,30 @@
+===============
+BO4E Versioning
+===============
+
+The BO4E data model uses a unique versioning system to track changes and updates.
+This system is easy to understand once you're familiar with its format and rationale.
+
+Let's break it down:
+
+Version Format: `YYYYMM.functional.technical`
+
+- YYYYMM: Represents the year (YYYY) and month (MM) when the version was released. For example, 202312 would mean December 2023.
+- functional: A number that changes when there are significant updates or new features.
+- technical: This number changes for minor updates, like bug fixes or spelling corrections.
+
+How Does it Work?
+=================
+
+1. **Base Structure**: Think of the version number as a date followed by two additional numbers, like 202312.1.2. Here, 202312 tells you the release date, 1 is the functional number, and 2 is the technical number.
+2. **Technical Changes**: If we fix a typo or a small bug, we only change the technical number. So, after a minor fix, the version might change from 202312.1.2 to 202312.1.3.
+3. **Functional Changes**: For bigger changes, like adding a new business object, we update the functional number and reset the technical number to zero. For instance, if we add a significant feature to the 202312.1.2 version, it becomes 202312.2.0.
+
+Yearly Reset: With the start of a new year, we reset both the functional and technical numbers.
+So, if we're moving from December 2023 (202312.2.0) to January 2024, the new version would be 202401.0.0.
+
+Why This System?
+================
+
+This versioning system, inspired by semantic versioning, offers a clear and systematic way to track changes.
+It ensures that users can easily identify when a significant update has occurred and when minor tweaks have been made.
diff --git a/src/bo4e/version.py b/src/bo4e/version.py
@@ -2,9 +2,12 @@
 Version information for the bo4e package.
 """
 import re
-from importlib.metadata import version
+from importlib.metadata import PackageNotFoundError, version
 
-__version__ = version("bo4e")
+try:
+    __version__ = version("bo4e")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
 # Please keep this name in sync with the name of the project in pyproject.toml
 # This name is the name of the package on pypi.org
 if re.match(r"^(\d+\.\d+\.\d+)(rc\d+)?$", __version__):