Use modern material theme for docs

[lc0rp]

Background

We're using a ReadTheDocs theme that hasn't changed in years, and isn't the default, more modern MkDocs theme.

@RaghavKumar suggested the Material UI theme, and after using it, the docs feel way more accessible.

It's also the most popular MkDocs theme, by far, according to https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes.

Changes

• Updated requirements.txt to include the mkdocs-material package
• Changed theme in mkdocs.yaml
• Configured some theme options like color schemes, navigation, etcetera
• Added logo to docs/imgs (for favicon)

Documentation

N/A - these are the docs

Test Plan

Played around with it in-browser for the past 3h :-(

PR Quality Checklist

• My pull request is atomic and focuses on a single change.
• I have thoroughly tested my changes with multiple different prompts.
• I have considered potential risks and mitigations for my changes.
• I have documented my changes clearly and comprehensively.
• I have not snuck in any "extra" small tweaks changes.
• I have run the following commands against my code to ensure it passes our linters:

  black .
  isort .
  mypy
  autoflake --remove-all-unused-imports --recursive --ignore-init-module-imports --ignore-pass-after-docstring autogpt tests --in-place

Preview:

[netlify]

❌ Deploy Preview for auto-gpt-docs failed.

Name	Link
🔨 Latest commit	d699ef6
🔍 Latest deploy log	https://app.netlify.com/sites/auto-gpt-docs/deploys/64c92fa8169cff0008e2bda9

[codecov]

Codecov Report

Patch and project coverage have no change.

Comparison is base (fc62552) 51.95% compared to head (d699ef6) 51.95%.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #5035   +/-   ##
=======================================
  Coverage   51.95%   51.95%           
=======================================
  Files         116      116           
  Lines        4987     4987           
  Branches      671      671           
=======================================
  Hits         2591     2591           
  Misses       2198     2198           
  Partials      198      198           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[collijk]

I think this is a great idea. I love material. Some things from my own technical documentation projects.

In the theme you can add:

theme:
    name: material
    features:
      - content.code.copy

and that will enable the little click to copy box in code snippets for people looking at our docs.

I also just blanket put in

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.snippets:
      auto_append:
        - includes/abbreviations.md
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde
  - tables
plugins:
  - table-reader
  - search
extra_javascript:
  - https://unpkg.com/[email protected]/dist/tablesort.min.js
  - _javascript/tablesort.js
  - _javascript/mathjax.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

and add

window.MathJax = {
  tex: {
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processEscapes: true,
    processEnvironments: true
  },
  options: {
    ignoreHtmlClass: ".*|",
    processHtmlClass: "arithmatex"
  }
};

document$.subscribe(() => {
  MathJax.typesetPromise()
})

to docs/_javascript/mathjax.js

and

document$.subscribe(function() {
  var tables = document.querySelectorAll("article table:not([class])")
  tables.forEach(function(table) {
    new Tablesort(table)
  })
})

to docs/_javascript/tablesort.js.

This set of stuff enables all the features in material (which are turned off by default).

[collijk]

Happy to let you decide what you want to include here, but would like to hear your thoughts.

[lc0rp]

These are great! Testing them now...

[Pwuts]

It seems to be missing the extension that does highlighting for indented code blocks

Changes have been addressed

[vittorio88]

@lc0rp @collijk I made a small correction to a sample YAML snippet that came from this PR. Would appreciate a review, thank you.
The PR is #5168 .