docs: add support

Author: ReenigneArcher

SUPPORT.md

@@ -0,0 +1,71 @@
+# Support
+
+> [!WARNING]
+> We use GitHub issues exclusively for actionable bug reports. Low-effort issues will be immediately closed.
+> Spamming the GitHub repo or organization will result in a ban.
+
+## Need support?
+
+**First, read the documentation!**
+
+### Read the Docs
+
+Select projects have the documentation hosted on Read the Docs. Otherwise, check the project's README file.
+
+**Type:** Documentation
+
+📖 [Read the Docs](https://docs.lizardbyte.dev/latest/about/overview.html)
+
+---
+
+## Need more help?
+
+**Ask questions**
+
+### Discord
+
+This is our preferred method of providing support!
+Please read the rules, be courteous, and use the appropriate channel when posting.
+
+**Type:** Primary Support
+
+💬 [Join our Discord](https://discord.com/invite/d6MpcrbYQs)
+
+### GitHub
+
+GitHub *Discussions* are available for support, feature requests, and general discourse.
+Please DO NOT use GitHub issues to ask for support!
+
+**Type:** Primary Support
+
+🐙 [GitHub Discussions](https://github.com/orgs/LizardByte/discussions)
+
+### Reddit
+
+For aliens only! Please read the rules, be courteous, and use the appropriate flair when posting.
+Provide your logs when asking for help.
+
+**Type:** Community Support
+
+👽 [r/LizardByte](https://www.reddit.com/r/LizardByte)
+
+---
+
+## Additional Resources
+
+- 📚 [Documentation](https://docs.lizardbyte.dev/latest/about/overview.html)
+- 🏠 [Homepage](https://app.lizardbyte.dev/)
+- 🔧 [Status Page](https://status.LizardByte.dev)
+- 📝 [Blog](https://app.lizardbyte.dev/blog)
+
+---
+
+## Support Guidelines
+
+When seeking support, please:
+
+1. **Read the documentation first** - Many common questions are answered in our comprehensive docs
+2. **Use the appropriate channel** - Discord and GitHub Discussions for primary support, Reddit for community support
+3. **Be courteous and respectful** - Follow community guidelines and be patient with volunteers
+4. **Provide detailed information** - Include logs, error messages, and system information when relevant
+5. **Use proper formatting** - Help others help you by formatting code and logs properly

docs/source/about/support.rst

@@ -1,7 +1,2 @@
-Support
-=======
-
-.. Warning:: We use GitHub issues exclusively for actionable bug reports. Low effort issues will be immediately closed.
-   Spamming the GitHub repo or organization will result in a ban.
-
-Our available support methods are listed in our `Support Center <https://app.lizardbyte.dev/support>`__.
+.. include:: ../../../SUPPORT.md
+   :parser: myst_parser.docutils_

docs/source/conf.py

@@ -39,6 +39,11 @@
     'sphinx_copybutton',  # add a copy button to code blocks
 ]
 
+# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
+myst_enable_extensions = [
+    "colon_fence",  # Only enabled so we can implement am adhoc fix to render GitHub admonitions
+]
+
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
 
@@ -94,3 +99,62 @@
 # disable epub mimetype warnings
 # https://github.com/readthedocs/readthedocs.org/blob/eadf6ac6dc6abc760a91e1cb147cc3c5f37d1ea8/docs/conf.py#L235-L236
 suppress_warnings = ["epub.unknown_project_files"]
+
+
+# Issue https://github.com/executablebooks/MyST-Parser/issues/845
+# GitHub admonitions with Sphinx/MyST
+# Workaround template adapted from (with some changes):
+# https://github.com/python-project-templates/yardang/blob/f77348d45dcf0eb130af304f79c0bfb92ab90e0c/yardang/conf.py.j2#L156-L188
+
+# https://spdx.github.io/spdx-spec/v2.3/file-tags/#h3-snippet-tags-format
+# SPDX-SnippetBegin
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-SnippetCopyrightText: Tim Paine / the yardang authors <t.paine154@gmail.com">
+
+_GITHUB_ADMONITIONS = {
+    "> [!NOTE]": "note",
+    "> [!TIP]": "tip",
+    "> [!IMPORTANT]": "important",
+    "> [!WARNING]": "warning",
+    "> [!CAUTION]": "caution",
+}
+
+
+def convert_gh_admonitions(app, relative_path, parent_docname, contents):
+    # TODO handle nested directives -> recursion
+    # loop through content lines, replace github admonitions
+    for i, orig_content in enumerate(contents):
+        orig_line_splits = orig_content.split("\n")
+        replacing = False
+        for j, line in enumerate(orig_line_splits):
+            # look for admonition key
+            line_roi = line.lstrip()
+            for admonition_key in _GITHUB_ADMONITIONS:
+                if line_roi.startswith(admonition_key):
+                    line = line.replace(admonition_key, ":::{" + _GITHUB_ADMONITIONS[admonition_key] + "}")
+                    # start replacing quotes in subsequent lines
+                    replacing = True
+                    break
+            else:  # no break
+                if not replacing:
+                    continue
+                # remove GH directive to match MyST directive
+                # since we are replacing on the original line, this will preserve the right indent, if any
+                if line_roi.startswith("> "):
+                    line = line.replace("> ", "", 1)
+                elif line_roi.rstrip() == ">":
+                    line = line.replace(">", "", 1)
+                else:
+                    # missing "> ", so stop replacing and terminate directive
+                    line = f":::\n{line}"
+                    replacing = False
+            # swap line back in splits
+            orig_line_splits[j] = line
+        # swap line back in original
+        contents[i] = "\n".join(orig_line_splits)
+
+# SPDX-SnippetEnd
+
+
+def setup(app):
+    app.connect("include-read", convert_gh_admonitions)