From 84203a021d1ddd1c9d9ce9962a81ebc72db58629 Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Tue, 19 Nov 2024 17:09:13 +0000 Subject: [PATCH] maint: Restructure docs configuration file and improve docs pages --- docs/source/conf.py | 87 +++++++++++----------- docs/source/user_guide/configuration.rst | 2 +- docs/source/user_guide/troubleshooting.rst | 2 +- 3 files changed, 44 insertions(+), 47 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 176a39d983..f1c38ea882 100644 --- a/docs/source/conf.py +++ b/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 +] diff --git a/docs/source/user_guide/configuration.rst b/docs/source/user_guide/configuration.rst index 6126541e21..92c2d2d17b 100644 --- a/docs/source/user_guide/configuration.rst +++ b/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 `_ + For ``mamba`` configuration, please refer to `conda documentation `_ The configuration is parsed/read from multiple sources types: diff --git a/docs/source/user_guide/troubleshooting.rst b/docs/source/user_guide/troubleshooting.rst index d6cd6d8f01..435f996775 100644 --- a/docs/source/user_guide/troubleshooting.rst +++ b/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 `_ +source: Robocop `troubleshooting documentation `_ 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