maint: Restructure docs configuration file and improve docs pages (#3615)

docs/source/conf.py

@@ -1,40 +1,60 @@
 # 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
+
+extensions = []
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+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
+
+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,
+}
+
+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 any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
+# Add Sphinx extension modules
 extensions = ["mermaid", "mermaid_inheritance", "myst_parser", "breathe"]
 
 # Configuration of Breathe Doxygen interopt
@@ -43,30 +63,7 @@ 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"]
-
-# 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 = []
-
-
-# -- Options for HTML output -------------------------------------------------
-
-# 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 = {
-    "repository_url": "https://github.com/mamba-org/mamba",
-    "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"]
+# 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