maint: Restructure docs configuration file and improve docs pages

docs/source/conf.py

@@ -1,72 +1,69 @@
 # Configuration file for the Sphinx documentation builder.
 #
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
+# For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Path setup --------------------------------------------------------------
-
-# 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
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-
-import os
-import sys
-from pathlib import Path
-
-# sys.path.insert(0, os.path.abspath('.'))
-
-
 # -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "mamba"
-copyright = "2020, QuantStack & mamba contributors"  # noqa
+copyright = "2024, QuantStack & mamba contributors"
 author = "QuantStack & mamba contributors"
 
-# The full version, including alpha/beta/rc tags
-release = "0.5.2"
-
+version = "latest"
+release = "latest"
 
 # -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-# Load local extensions (e.g. mermaid)
-sys.path.insert(0, str(Path.cwd().resolve() / "tools"))
+extensions = []
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = ["mermaid", "mermaid_inheritance", "myst_parser", "breathe"]
-
-# Configuration of Breathe Doxygen interopt
-breathe_projects = {"libmamba": os.environ.get("MAMBA_DEV_DOXYGEN_XML_DIR", "../xml")}
-breathe_default_project = "libmamba"
-breathe_default_members = ("members", "undoc-members")
-breathe_show_include = False
-
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
-
+language = "en"
 
 # -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+html_static_path = ["_static"]
+
+# The file above was generated using sphinx 8.1.3 with this command:
+# sphinx-quickstart --project "mamba" --author "QuantStack & mamba contributors" -v "latest" -r "latest" -l en --no-sep --no-makefile --no-batchfile
+# These are custom options for this project
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
 html_theme = "sphinx_book_theme"
 html_logo = "_static/logo.png"
 html_title = "documentation"
 
 html_theme_options = {
+    "path_to_docs": "docs/source",
+    "repository_branch": "main",
     "repository_url": "https://github.com/mamba-org/mamba",
+    "use_download_button": True,
+    "use_edit_page_button": True,
+    "use_issues_button": True,
     "use_repository_button": True,
 }
 
-# Add any paths that contain custom static files (such as style sheets) here,
-# 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"]
+import os  # noqa: E402
+import sys  # noqa: E402
+from pathlib import Path  # noqa: E402
+
+# Load local extensions (e.g. mermaid)
+sys.path.insert(0, str(Path.cwd().resolve() / "tools"))
+
+# Add Sphinx extension modules
+extensions = ["mermaid", "mermaid_inheritance", "myst_parser", "breathe"]
+
+# Configuration of Breathe Doxygen interopt
+breathe_projects = {"libmamba": os.environ.get("MAMBA_DEV_DOXYGEN_XML_DIR", "../xml")}
+breathe_default_project = "libmamba"
+breathe_default_members = ("members", "undoc-members")
+breathe_show_include = False
+
+# Configure links which should be ignored during linkcheck
+linkcheck_ignore = [
+    r".*github\.com.*#",  # javascript based anchors
+]

docs/source/user_guide/configuration.rst

@@ -10,7 +10,7 @@ While ``mamba`` currently relies on ``conda`` configuration, ``libmamba`` and do
 rely on a pure C++ implementation.
 
 .. note::
-  For ``mamba`` configuration, please refer to `conda documentation <https://conda.io/projects/conda/en/latest/user-guide/configuration/index.html>`_
+  For ``mamba`` configuration, please refer to `conda documentation <https://docs.conda.io/projects/conda/en/latest/user-guide/configuration/index.html>`_
 
 The configuration is parsed/read from multiple sources types:
 

docs/source/user_guide/troubleshooting.rst

@@ -118,7 +118,7 @@ Windows API historically supports paths up to 260 characters. While it's now pos
 Long paths support has to be activated
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-source: Robocop `troubleshooting documentation <https://robocorp.com/docs/troubleshooting/windows-long-path>`_
+source: Robocop `troubleshooting documentation <https://sema4.ai/docs/automation/troubleshooting/windows-long-path>`_
 
 1. Open the Local Group Policy Editor application: - Start --> type gpedit.msc --> Enter:
 2. Navigate to Computer Configuration > Administrative Templates > System > Filesystem. On the right, find the "Enable win32 long paths" item and double-click it