Switching to conda-sphinx-theme plus reorganizing the site a bit (#370)

Co-authored-by: jaimergp <jaimergp@users.noreply.github.com> Co-authored-by: Jannis Leidel <jannis@leidel.info>
conda · Nov 10, 2023 · 125b9b2 · 125b9b2
1 parent ab99449
commit 125b9b2
Show file tree

Hide file tree

Showing 15 changed files with 150 additions and 68 deletions.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -17,4 +17,4 @@ Thank you for helping make this a welcoming, friendly community for all.
 
 * Report a code of conduct incident [using a form](https://form.jotform.com/221527028480048).
 * Report a code of conduct incident via email: [conduct@conda.org](mailto:conduct@conda.org).
-* Contact [an individual committee member](#committee-membership) or [CoC event representative](#coc-representatives) to report an incident in confidence.
+* Contact [an individual committee member](https://github.com/conda-incubator/governance/blob/main/CODE_OF_CONDUCT.md#committee-membership) or [CoC event representative](https://github.com/conda-incubator/governance/blob/main/CODE_OF_CONDUCT.md#coc-representatives) to report an incident in confidence.
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
diff --git a/docs/_templates/navbar_center.html b/docs/_templates/navbar_center.html
@@ -0,0 +1,14 @@
+<ul id="navbar-main-elements" class="navbar-nav">
+    <li class="nav-item current active">
+        <a class="reference internal nav-link" href="{{ pathto("index") }}">{{ project }}</a>
+    </li>
+    <li class="nav-item {% if project == "conda" %}current active{% endif %}">
+        <a class="reference internal nav-link" href="https://docs.conda.io/projects/conda/">Conda</a>
+    </li>
+    <li class="nav-item {% if project == "conda-build" %}current active{% endif %}">
+        <a class="reference internal nav-link" href="https://docs.conda.io/projects/conda-build/">Conda-build</a>
+    </li>
+    <li class="nav-item {% if project == "miniconda" %}current active{% endif %}">
+        <a class="reference internal nav-link" href="https://docs.conda.io/projects/miniconda/">Miniconda</a>
+    </li>
+</ul>
diff --git a/docs/conf.py b/docs/conf.py
@@ -28,6 +28,7 @@
     "sphinx_sitemap",
     "sphinx_design",
     "sphinx_copybutton",
+    "sphinx_reredirects",
 ]
 
 myst_heading_anchors = 3
@@ -52,7 +53,7 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "pydata_sphinx_theme"
+html_theme = "conda_sphinx_theme"
 html_static_path = ["_static"]
 
 html_css_files = [
@@ -63,14 +64,29 @@
 html_extra_path = ["robots.txt"]
 
 html_theme_options = {
-    "github_url": "https://github.com/conda/conda-libmamba-solver",
-    "collapse_navigation": True,
-    "navigation_depth": 1,
+    "navigation_depth": -1,
     "use_edit_page_button": True,
-    "show_toc_level": 1,
-    "navbar_align": "left",
-    "header_links_before_dropdown": 1,
-    # "announcement": "<p>This is the documentation of the new conda-libmamba-solver plugin!</p>",
+    "navbar_center": ["navbar_center"],
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/conda/conda-libmamba-solver",
+            "icon": "fa-brands fa-square-github",
+            "type": "fontawesome",
+        },
+        {
+            "name": "Element",
+            "url": "https://matrix.to/#/#conda-libmamba-solver:matrix.org",
+            "icon": "_static/element_logo.svg",
+            "type": "local",
+        },
+        {
+            "name": "Discourse",
+            "url": "https://conda.discourse.group/",
+            "icon": "fa-brands fa-discourse",
+            "type": "fontawesome",
+        },
+    ],
 }
 
 html_context = {
@@ -84,3 +100,15 @@
 sitemap_locales = [None]
 # We're hard-coding stable here since that's what we want Google to point to.
 sitemap_url_scheme = "{link}"
+
+# -- For sphinx_reredirects ------------------------------------------------
+
+redirects = {
+    "getting-started": "user-guide",
+    "faq": "user-guide/faq",
+    "configuration": "user-guide/configuration",
+    "libmamba-vs-classic": "user-guide/libmamba-vs-classic",
+    "more-resources": "user-guide/more-resources",
+    "performance": "user-guide/performance",
+    "subcommands": "user-guide/subcommands",
+}
diff --git a/docs/dev/index.md b/docs/dev/index.md
@@ -0,0 +1,14 @@
+# Developer Guide
+
+To get started with developing conda-libmamba-solver, please check out
+the following pages:
+
+```{toctree}
+:maxdepth: 1
+setup
+workflows
+implementation
+future-work
+code-of-conduct
+changelog
+```
diff --git a/docs/environment.yml b/docs/environment.yml
@@ -3,6 +3,7 @@ channels:
   - conda-forge
   - defaults
 dependencies:
+  - accessible-pygments=0.0.4
   - alabaster=0.7.12
   - babel=2.11.0
   - beautifulsoup4=4.11.1
@@ -23,42 +24,43 @@ dependencies:
   - libsqlite=3.40.0
   - libzlib=1.2.13
   - linkify-it-py=2.0.0
-  - markdown-it-py=2.1.0
+  - markdown-it-py=3.0.0
   - markupsafe=2.1.1
-  - mdit-py-plugins=0.3.1
+  - mdit-py-plugins=0.4.0
   - mdurl=0.1.0
-  - myst-parser=0.18.1
+  - myst-parser=2.0.0
   - ncurses=6.3
   - openssl=3.0.7
   - packaging=21.3
   - pip=22.3.1
   - pycparser=2.21
-  - pydata-sphinx-theme=0.12.0
-  - pygments=2.13.0
+  - pydata-sphinx-theme=0.14.3
+  - pygments=2.16.1
   - pyopenssl=22.1.0
   - pyparsing=3.0.9
   - pysocks=1.7.1
   - python=3.11.0
   - python_abi=3.11
   - pytz=2022.6
-  - pyyaml=6.0
+  - pyyaml=6.0.1
   - readline=8.1.2
   - requests=2.28.1
   - setuptools=65.5.1
   - six=1.16.0
   - snowballstemmer=2.2.0
   - soupsieve=2.3.2.post1
-  - sphinx=5.3.0
+  - sphinx=7.2.6
   - sphinx-copybutton=0.5.0
-  - sphinx-design=0.3.0
+  - sphinx-design=0.5.0
   - sphinx-sitemap=2.2.1
+  - sphinx-reredirects=0.1.2
   - sphinxcontrib-applehelp=1.0.2
   - sphinxcontrib-devhelp=1.0.2
   - sphinxcontrib-htmlhelp=2.0.0
   - sphinxcontrib-jsmath=1.0.1
   - sphinxcontrib-mermaid=0.7.1
   - sphinxcontrib-qthelp=1.0.3
-  - sphinxcontrib-serializinghtml=1.1.5
+  - sphinxcontrib-serializinghtml=1.1.9
   - tk=8.6.12
   - typing-extensions=4.4.0
   - typing_extensions=4.4.0
@@ -69,3 +71,5 @@ dependencies:
   - xz=5.2.6
   - yaml=0.2.5
   - zipp=3.10.0
+  - pip:
+      - conda-sphinx-theme==0.1.1
diff --git a/docs/index.md b/docs/index.md
@@ -1,44 +1,50 @@
----
-sd_hide_title: true
----
 # conda-libmamba-solver
 
+Welcome to the conda-libmamba-solver documentation! The conda-libmamba-solver
+was written to make conda faster and is now the default solver. On this site,
+you will find information about how to configure and use this solver.
+
+## Learn
+
 ::::{grid} 2
-:::{grid-item-card} User guide
-Start here if you want a faster conda:
-^^^
-```{toctree}
-:maxdepth: 1
-getting-started
-subcommands
-configuration
-libmamba-vs-classic
-performance
-faq
-more-resources
-```
-+++
-Found a bug? [File an issue here](https://github.com/conda/conda-libmamba-solver/issues/new/choose)
 
+:::{grid-item-card} Getting started
+:link: user-guide/index
+:link-type: doc
+New to conda-libmamba-solver? Start here to learn the essentials
 :::
 
-:::{grid-item-card} Developer guide
+:::{grid-item-card} Configuration
+:link: user-guide/configuration
+:link-type: doc
+Learn about all available configuration options
 
-If you want to contribute:
-^^^
+::::
 
-```{toctree}
-:maxdepth: 1
-dev/setup
-dev/workflows
-dev/implementation
-dev/future-work
-dev/code-of-conduct
-dev/changelog
-```
-+++
-[Code repository](https://github.com/conda/conda-libmamba-solver), [Project board](https://github.com/orgs/conda/projects/15)
+## Development
+
+::::{grid} 2
 
+:::{grid-item-card} Development environment
+:link: dev/setup
+:link-type: doc
+Learn how to set up your development environment
 :::
 
+:::{grid-item-card} Changelog
+:link: dev/changelog
+:link-type: doc
+Recent changes and udpates to the project
 ::::
+
+
+```{seealso}
+Found a bug? [File an issue here](https://github.com/conda/conda-libmamba-solver/issues/new/choose)
+```
+
+```{toctree}
+:hidden:
+
+user-guide/index
+dev/index
+```
diff --git a/docs/configuration.md → docs/user-guide/configuration.md b/docs/configuration.md → docs/user-guide/configuration.md
diff --git a/docs/faq.md → docs/user-guide/faq.md b/docs/faq.md → docs/user-guide/faq.md
@@ -2,8 +2,8 @@
 
 ## What's the difference between the available solvers in `conda`?
 
-Please refer to the section "Differences between `libmamba` and `classic`" in
-the [`libmamba-vs-classic`](./libmamba-vs-classic.md#differences-between-libmamba-and-classic) docs.
+Please refer to the section "Technical differences between `libmamba` and `classic`" in
+the [`libmamba-vs-classic`](./libmamba-vs-classic.md#technical-differences-between-libmamba-and-classic) docs.
 
 ## How do I uninstall it?
 

diff --git a/docs/getting-started.md → docs/user-guide/index.md b/docs/getting-started.md → docs/user-guide/index.md
@@ -1,4 +1,4 @@
-# Getting started
+# User Guide
 
 The `conda-libmamba-solver` plugin allows you to use `libmamba`, the same `libsolv`-powered solver used by `mamba` and `micromamba`, directly in `conda`.
 
@@ -57,3 +57,14 @@ Finally, if you need to revert the default configuration back to `classic`, you
 If you are unsure what configuration is being used by conda, you can inspect
 it with `conda config --show-sources`.
 ```
+
+```{toctree}
+:hidden:
+
+subcommands
+configuration
+faq
+libmamba-vs-classic
+performance
+more-resources
+```
diff --git a/docs/libmamba-vs-classic.md → docs/user-guide/libmamba-vs-classic.md b/docs/libmamba-vs-classic.md → docs/user-guide/libmamba-vs-classic.md
diff --git a/docs/more-resources.md → docs/user-guide/more-resources.md b/docs/more-resources.md → docs/user-guide/more-resources.md
diff --git a/docs/performance.md → docs/user-guide/performance.md b/docs/performance.md → docs/user-guide/performance.md
diff --git a/docs/subcommands.md → docs/user-guide/subcommands.md b/docs/subcommands.md → docs/user-guide/subcommands.md
diff --git a/news/370-use-conda-sphinx-theme b/news/370-use-conda-sphinx-theme
@@ -0,0 +1,20 @@
+### Enhancements
+
+* <news item>
+
+### Bug fixes
+
+* <news item>
+
+### Deprecations
+
+* <news item>
+
+### Docs
+
+* Use new conda-sphinx-theme for documentation site. (#367 via #370)
+* Reorganize the layout of the documentation site. (#370)
+
+### Other
+
+* <news item>