From 0c68eb338ccb369692845d59347b30387479960e Mon Sep 17 00:00:00 2001 From: Rapptz Date: Thu, 16 Feb 2023 10:45:53 -0500 Subject: [PATCH] Add colour previews to the documentation --- discord/colour.py | 136 ++++++++++++++++++++++++------ docs/conf.py | 1 + docs/extensions/colour_preview.py | 51 +++++++++++ 3 files changed, 164 insertions(+), 24 deletions(-) create mode 100644 docs/extensions/colour_preview.py diff --git a/discord/colour.py b/discord/colour.py index a3e4de031..f271b11cd 100644 --- a/discord/colour.py +++ b/discord/colour.py @@ -209,7 +209,10 @@ class Colour: @classmethod def default(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0``.""" + """A factory method that returns a :class:`Colour` with a value of ``0``. + + .. colour:: #000000 + """ return cls(0) @classmethod @@ -235,148 +238,225 @@ class Colour: @classmethod def teal(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0x1ABC9C``.""" + """A factory method that returns a :class:`Colour` with a value of ``0x1ABC9C``. + + .. colour:: #1ABC9C + """ return cls(0x1ABC9C) @classmethod def dark_teal(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0x11806A``.""" + """A factory method that returns a :class:`Colour` with a value of ``0x11806A``. + + .. colour:: #11806A + """ return cls(0x11806A) @classmethod def brand_green(cls) -> Self: """A factory method that returns a :class:`Colour` with a value of ``0x57F287``. + .. colour:: #57F287 + + .. versionadded:: 2.0 """ return cls(0x57F287) @classmethod def green(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0x2ECC71``.""" + """A factory method that returns a :class:`Colour` with a value of ``0x2ECC71``. + + .. colour:: #2ECC71 + """ return cls(0x2ECC71) @classmethod def dark_green(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0x1F8B4C``.""" + """A factory method that returns a :class:`Colour` with a value of ``0x1F8B4C``. + + .. colour:: #1F8B4C + """ return cls(0x1F8B4C) @classmethod def blue(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0x3498DB``.""" + """A factory method that returns a :class:`Colour` with a value of ``0x3498DB``. + + .. colour:: #3498DB + """ return cls(0x3498DB) @classmethod def dark_blue(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0x206694``.""" + """A factory method that returns a :class:`Colour` with a value of ``0x206694``. + + .. colour:: #206694 + """ return cls(0x206694) @classmethod def purple(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0x9B59B6``.""" + """A factory method that returns a :class:`Colour` with a value of ``0x9B59B6``. + + .. colour:: #9B59B6 + """ return cls(0x9B59B6) @classmethod def dark_purple(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0x71368A``.""" + """A factory method that returns a :class:`Colour` with a value of ``0x71368A``. + + .. colour:: #71368A + """ return cls(0x71368A) @classmethod def magenta(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0xE91E63``.""" + """A factory method that returns a :class:`Colour` with a value of ``0xE91E63``. + + .. colour:: #E91E63 + """ return cls(0xE91E63) @classmethod def dark_magenta(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0xAD1457``.""" + """A factory method that returns a :class:`Colour` with a value of ``0xAD1457``. + + .. colour:: #AD1457 + """ return cls(0xAD1457) @classmethod def gold(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0xF1C40F``.""" + """A factory method that returns a :class:`Colour` with a value of ``0xF1C40F``. + + .. colour:: #F1C40F + """ return cls(0xF1C40F) @classmethod def dark_gold(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0xC27C0E``.""" + """A factory method that returns a :class:`Colour` with a value of ``0xC27C0E``. + + .. colour:: #C27C0E + """ return cls(0xC27C0E) @classmethod def orange(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0xE67E22``.""" + """A factory method that returns a :class:`Colour` with a value of ``0xE67E22``. + + .. colour:: #E67E22 + """ return cls(0xE67E22) @classmethod def dark_orange(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0xA84300``.""" + """A factory method that returns a :class:`Colour` with a value of ``0xA84300``. + + .. colour:: #A84300 + """ return cls(0xA84300) @classmethod def brand_red(cls) -> Self: """A factory method that returns a :class:`Colour` with a value of ``0xED4245``. + .. colour:: #ED4245 + .. versionadded:: 2.0 """ return cls(0xED4245) @classmethod def red(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0xE74C3C``.""" + """A factory method that returns a :class:`Colour` with a value of ``0xE74C3C``. + + .. colour:: #E74C3C + """ return cls(0xE74C3C) @classmethod def dark_red(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0x992D22``.""" + """A factory method that returns a :class:`Colour` with a value of ``0x992D22``. + + .. colour:: #992D22 + """ return cls(0x992D22) @classmethod def lighter_grey(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0x95A5A6``.""" + """A factory method that returns a :class:`Colour` with a value of ``0x95A5A6``. + + .. colour:: #95A5A6 + """ return cls(0x95A5A6) lighter_gray = lighter_grey @classmethod def dark_grey(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0x607d8b``.""" + """A factory method that returns a :class:`Colour` with a value of ``0x607d8b``. + + .. colour:: #607d8b + """ return cls(0x607D8B) dark_gray = dark_grey @classmethod def light_grey(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0x979C9F``.""" + """A factory method that returns a :class:`Colour` with a value of ``0x979C9F``. + + .. colour:: #979C9F + """ return cls(0x979C9F) light_gray = light_grey @classmethod def darker_grey(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0x546E7A``.""" + """A factory method that returns a :class:`Colour` with a value of ``0x546E7A``. + + .. colour:: #546E7A + """ return cls(0x546E7A) darker_gray = darker_grey @classmethod def og_blurple(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0x7289DA``.""" + """A factory method that returns a :class:`Colour` with a value of ``0x7289DA``. + + .. colour:: #7289DA + """ return cls(0x7289DA) @classmethod def blurple(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0x5865F2``.""" + """A factory method that returns a :class:`Colour` with a value of ``0x5865F2``. + + .. colour:: #5865F2 + """ return cls(0x5865F2) @classmethod def greyple(cls) -> Self: - """A factory method that returns a :class:`Colour` with a value of ``0x99AAB5``.""" + """A factory method that returns a :class:`Colour` with a value of ``0x99AAB5``. + + .. colour:: #99AAB5 + """ return cls(0x99AAB5) @classmethod def dark_theme(cls) -> Self: """A factory method that returns a :class:`Colour` with a value of ``0x36393F``. + This will appear transparent on Discord's dark theme. + .. colour:: #36393F + .. versionadded:: 1.5 """ return cls(0x36393F) @@ -385,6 +465,8 @@ class Colour: def fuchsia(cls) -> Self: """A factory method that returns a :class:`Colour` with a value of ``0xEB459E``. + .. colour:: #EB459E + .. versionadded:: 2.0 """ return cls(0xEB459E) @@ -393,6 +475,8 @@ class Colour: def yellow(cls) -> Self: """A factory method that returns a :class:`Colour` with a value of ``0xFEE75C``. + .. colour:: #FEE75C + .. versionadded:: 2.0 """ return cls(0xFEE75C) @@ -401,6 +485,8 @@ class Colour: def dark_embed(cls) -> Self: """A factory method that returns a :class:`Colour` with a value of ``0x2F3136``. + .. colour:: #2F3136 + .. versionadded:: 2.2 """ return cls(0x2F3136) @@ -409,6 +495,8 @@ class Colour: def light_embed(cls) -> Self: """A factory method that returns a :class:`Colour` with a value of ``0xF2F3F5``. + .. colour:: #F2F3F5 + .. versionadded:: 2.2 """ return cls(0xF2F3F5) diff --git a/docs/conf.py b/docs/conf.py index 5d9ec7be4..8fee2cbfa 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -42,6 +42,7 @@ extensions = [ 'attributetable', 'resourcelinks', 'nitpick_file_ignorer', + 'colour_preview', ] autodoc_member_order = 'bysource' diff --git a/docs/extensions/colour_preview.py b/docs/extensions/colour_preview.py new file mode 100644 index 000000000..ae352b090 --- /dev/null +++ b/docs/extensions/colour_preview.py @@ -0,0 +1,51 @@ +from __future__ import annotations +from typing import Dict, Any + +from sphinx.util.docutils import SphinxDirective +from docutils.parsers.rst import directives +from docutils import nodes + +import sphinx +from sphinx.application import Sphinx + + +class colour_input(nodes.General, nodes.Element): + pass + + +def visit_colour_node(self, node): + self.body.append( + self.starttag( + node, + 'input', + empty=True, + type='color', + value=node.rawsource, + disabled='', + CLASS=node.attributes.get('class', ''), + ) + ) + + +def depart_colour_node(self, node): + pass + + +class ColourDirective(SphinxDirective): + required_arguments = 1 + has_content = False + + option_spec = { + 'class': directives.class_option, + } + + def run(self): + node = colour_input(self.arguments[0], **self.options) + self.state.nested_parse(self.content, self.content_offset, node) + return [node] + + +def setup(app: Sphinx) -> Dict[str, Any]: + app.add_node(colour_input, html=(visit_colour_node, depart_colour_node)) + app.add_directive('colour', ColourDirective) + return {'version': sphinx.__display_version__, 'parallel_read_safe': True}