Merge pull request #6 from XXII-AI/docs/update_fiftyone_inv

Update docs

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Move codebase to github
+- Move doc to readthedocs.io #6
 
 ## Archived changelog
 

README.md

@@ -6,8 +6,8 @@ A lib to help R&D team with its experiments.
 
 Sphinx docs is available here:
 
-- [stable](UPDATE-ME)
-- [latest](UPDATE-ME)
+- [stable](https://lours.readthedocs.io/stable/)
+- [latest](https://lours.readthedocs.io/latest/)
 
 ## Installation
 
@@ -73,4 +73,4 @@ print(dataset2)
 
 See some notebooks in folder `docs/notebooks`
 
-Alternatively, See <UPDATE-ME/stable/tutorials>
+Alternatively, See <https://lours.readthedocs.io/stable/tutorials>

docs/_static/version_switcher.json

@@ -2,11 +2,11 @@
   {
     "name": "v0.1.0",
     "version": "0.1.0",
-    "url": "UPDATE-ME/stable/"
+    "url": "https://lours.readthedocs.io/stable/"
   },
   {
     "name": "dev (latest)",
     "version": "dev",
-    "url": "UPDATE-ME/latest/"
+    "url": "https://lours.readthedocs.io/latest/"
   }
 ]

docs/conf.py

@@ -12,23 +12,15 @@
 #
 import os
 import sys
-from datetime import date
-
-import toml
 
 sys.path.insert(0, os.path.abspath(".."))
+import lours
 
-release = os.getenv("SPHINX_RELEASE", "develop")
-base_url = os.getenv("CI_PAGES_URL")
-version_switcher = os.getenv("VERSION_SWITCHER")
-version_match = os.getenv("VERSION_MATCH")
 
 # -- Project information -----------------------------------------------------
-with open("../pyproject.toml") as f:
-    project_metadata = toml.load(f)
-project = project_metadata["tool"]["poetry"]["name"]
-author = ", ".join(project_metadata["tool"]["poetry"]["authors"])
-copyright = f"{date.today().year}, XXII"
+project = "Lours"
+author = "Lours community"
+copyright = "2024, XXII"
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -37,21 +29,53 @@
 #
 html_theme = "pydata_sphinx_theme"
 html_logo = "_static/logo.png"
+
+# Define the json_url for our version switcher.
+json_url = "https://lours.readthedocs.io/en/latest/_static/switcher.json"
+
+# Define the version we use for matching in the version switcher.
+version_match = os.environ.get("READTHEDOCS_VERSION")
+release = lours.__version__
+# If READTHEDOCS_VERSION doesn't exist, we're not on RTD
+# If it is an integer, we're in a PR build and the version isn't correct.
+# If it's "latest" → change to "dev" (that's what we want the switcher to call it)
+if not version_match or version_match.isdigit() or version_match == "latest":
+    # For local development, infer the version to match from the package.
+    if "dev" in release or "rc" in release:
+        version_match = "dev"
+        # We want to keep the relative reference if we are in dev mode
+        # but we want the whole url if we are effectively in a released version
+        json_url = "_static/switcher.json"
+    else:
+        version_match = f"v{release}"
+elif version_match == "stable":
+    version_match = f"v{release}"
+
 html_theme_options = {
     "navbar_align": "left",
     "logo": {
-        "text": f"Lours {release} documentation",
+        "text": "Lours documentation",
     },
+    "external_links": [
+        {
+            "url": "https://www.xxiiai.com/",
+            "name": "XXII",
+        }],
     "icon_links": [
         {
-            "name": "GitLab",
-            "url": "UPDATE-ME",
-            "icon": "fa-brands fa-gitlab",
+            "name": "GitHub",
+            "url": "https://github.com/XXII-AI/Lours",
+            "icon": "fa-brands fa-github",
             "type": "fontawesome",
         },
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/lours/",
+            "icon": "fa-custom fa-pypi",
+        },
     ],
     "switcher": {
-        "json_url": f"{base_url}/{version_switcher}",
+        "json_url": json_url,
         "version_match": version_match,
     },
     "check_switcher": False,
@@ -97,7 +121,7 @@
 autodoc_typehints_format = "short"
 python_use_unqualified_type_names = True
 nbsphinx_allow_errors = True
-nbsphinx_execute = os.getenv("NBSPHINX_EXECUTE", "auto")
+nbsphinx_execute = "auto"
 add_module_names = False
 copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
 copybutton_prompt_is_regexp = True
@@ -112,11 +136,12 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+html_js_files = ["pypi.js"]
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "pandas": ("https://pandas.pydata.org/docs/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "pot": ("https://pythonot.github.io/", None),
-    "fiftyone": ("https://voxel51.com/docs/fiftyone/", None),
+    "fiftyone": ("https://docs.voxel51.com/", None),
 }