Update docs

TDKorn · TDKorn · commit 4c387bf80f72 · 2024-01-21T00:39:18.000-05:00
diff --git a/docs/source/README.rst b/docs/source/README.rst
@@ -53,7 +53,8 @@ GitHub source code links and syntax highlighting for Sphinx docs
 About
 ~~~~~~~~~~~~~
 
-``sphinx-github-style`` is a Sphinx extension that makes your docs look like and link to GitHub
+``sphinx-github-style`` is a Sphinx extension that links your documentation to GitHub source code.
+It also adds syntax highlighting for code blocks similar to GitHub's pretty lights dark theme.
 
 ...
 
@@ -62,33 +63,42 @@ GitHub Source Code Links
 ===============================
 
 
-Using :mod:`sphinx.ext.linkcode`,  a ``View on GitHub`` link is added to the documentation of every class, method and function:
+Using :mod:`sphinx.ext.linkcode`,  a ``View on GitHub`` link is added to the documentation of every class, method, function, and property:
 
-.. image:: https://user-images.githubusercontent.com/96394652/220941352-f5530a56-d338-4b90-b83a-4b22b0f632fe.png
-   :alt: sphinx github style adds a "View on GitHub" link
+.. only:: html
 
-They link to and highlight the corresponding code block in your GitHub repo:
+   .. autofunction:: sphinx_github_style.__init__.get_repo_dir
+      :no-index:
 
-.. image:: https://user-images.githubusercontent.com/96394652/220945912-447173db-2ac7-4e00-bec5-3859753bf687.png
+.. only:: not html
+
+   .. image:: https://user-images.githubusercontent.com/96394652/220941352-f5530a56-d338-4b90-b83a-4b22b0f632fe.png
+      :alt: sphinx github style adds a "View on GitHub" link
+
+
+They link to and highlight the corresponding code block in your GitHub repository:
+
+
+.. image:: _static/github_linked_code.png
 
 
-|
 
 .. note::
 
    These links can be used with/instead of the links added by :mod:`sphinx.ext.viewcode`
-     * They use a newly added ``linkcode-link`` class which can be styled using CSS
+     * They use a newly added ``linkcode-link`` class which can be :doc:`styled using CSS <add_linkcode_class>`
 
 
-|
 
 Syntax Highlighting
 ====================
 
-``sphinx-github-style`` **also contains a** ``Pygments`` **style to highlight code in your documentation similar to GitHub:**
+``sphinx-github-style`` **also contains a** ``Pygments`` **style to highlight code blocks similar to GitHub:**
 
 
-.. image:: https://user-images.githubusercontent.com/96394652/220946796-bf7aa236-964d-48e7-83e2-142aac00b0dd.png
+.. literalinclude:: ../../sphinx_github_style/__init__.py
+   :language: python
+   :lines: 230-246
 
 
 |
@@ -127,7 +137,6 @@ Add any (or none) of the following configuration variables to your ``conf.py``
    The name of the package's top-level module. For this repo, it would be ``sphinx_github_style``
 
    :type: **str**
-   :default: Return value from :func:`~.get_top_level`
 
 
 ``linkcode_blob``
@@ -178,15 +187,3 @@ Add any (or none) of the following configuration variables to your ``conf.py``
 
    :type: **Callable**
    :default: Return value from :func:`~.get_linkcode_resolve`
-
-
-|
-
-Noteworthy Components
-~~~~~~~~~~~~~~~~~~~~~
-
-* :class:`~.TDKStyle` - Pygments Style for syntax highlighting similar to Github Pretty Lights Dark Theme
-* :class:`~.TDKMethLexer` - Pygments Lexer to add syntax highlighting to methods
-* :func:`~.get_linkcode_resolve` - to link to GitHub source code using ``sphinx.ext.linkcode``
-* :func:`~.add_linkcode_node_class` - adds a new ``linkcode-link`` class, allowing for CSS styling separately from ``viewcode`` links
-* |.github_style|_ - CSS styling for linkcode links (icon + text)
diff --git a/docs/source/_static/github_linked_code.png b/docs/source/_static/github_linked_code.png
diff --git a/docs/source/add_linkcode_class.rst b/docs/source/add_linkcode_class.rst
@@ -1,11 +1,9 @@
 .. |.github_style| replace:: ``github_style.css``
 .. _.github_style: https://github.com/tdkorn/sphinx-github-style/tree/v1.0.0/sphinx_github_style/_static/github_style.css
 
-The ``add_linkcode_class`` module
+CSS Styling for Linkcode Links
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Add Linkcode Class for CSS Styling
-
 .. automodule:: sphinx_github_style.add_linkcode_class
    :members:
    :undoc-members:
diff --git a/docs/source/github_style.rst b/docs/source/github_style.rst
@@ -1,9 +1,6 @@
-The ``github_style`` module
+GitHub Dark Theme Pygments Style
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-:class:`~.TDKStyle` - GitHub Dark Theme Pygments Style
-===========================================================
-
 .. automodule:: sphinx_github_style.github_style
    :members:
    :undoc-members:
diff --git a/docs/source/lexer.rst b/docs/source/lexer.rst
@@ -0,0 +1,9 @@
+Pygments Lexer for Syntax Highlighting of Methods, Classes, Type Hints, and more
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: sphinx_github_style.lexer
+   :members:
+   :undoc-members:
+   :exclude-members: setup
+
+
diff --git a/docs/source/meth_lexer.rst b/docs/source/meth_lexer.rst
diff --git a/docs/source/modules.rst b/docs/source/modules.rst
@@ -14,4 +14,4 @@ The ``sphinx_github_style`` Package
 
    add_linkcode_class
    github_style
-   meth_lexer
+   lexer
diff --git a/setup.py b/setup.py
@@ -20,7 +20,7 @@ def get_version():
 setup(
     name="sphinx-github-style",
     version=get_version(),
-    description="Sphinx Github Integration and Github Dark Theme Pygments Style",
+    description="GitHub source code links and syntax highlighting for Sphinx documentation",
     long_description=read(LONG_DESCRIPTION_SRC),
     long_description_content_type="text/x-rst; charset=UTF-8",
     author="Adam Korn",
diff --git a/sphinx_github_style/__init__.py b/sphinx_github_style/__init__.py
@@ -13,8 +13,8 @@
 __author__ = 'Adam Korn <hello@dailykitten.net>'
 
 from .add_linkcode_class import add_linkcode_node_class
-from .meth_lexer import TDKMethLexer
 from .github_style import TDKStyle
+from .lexer import TDKLexer
 
 
 def setup(app: Sphinx) -> Dict[str, Any]:
@@ -32,7 +32,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     repo_dir = get_repo_dir()
 
     top_level = get_conf_val(app, 'top_level')
-    TDKMethLexer.TOP_LEVEL = top_level
+    TDKLexer.TOP_LEVEL = top_level
 
     if not callable(linkcode_func):
         print(
@@ -60,8 +60,8 @@ def add_static_path(app) -> None:
 
 
 def add_lexer(app: Sphinx, env) -> None:
-    """Registers the :class:`~.TDKMethLexer` to add GitHub dark syntax highlighting"""
-    app.add_lexer('python', TDKMethLexer.get_pkg_lexer())
+    """Registers the :class:`~.TDKLexer` to add better syntax highlighting"""
+    app.add_lexer('python', TDKLexer.get_pkg_lexer())
 
 
 def get_linkcode_revision(blob: str) -> str:
@@ -177,9 +177,9 @@ def linkcode_resolve(domain, info):
         modname = info['module']
         fullname = info['fullname']
 
-        if TDKMethLexer.TOP_LEVEL is None:
+        if TDKLexer.TOP_LEVEL is None:
             pkg_name = modname.split('.')[0]
-            TDKMethLexer.TOP_LEVEL = pkg_name
+            TDKLexer.TOP_LEVEL = pkg_name
 
         submod = sys.modules.get(modname)
         if submod is None:
diff --git a/sphinx_github_style/github_style.py b/sphinx_github_style/github_style.py
@@ -42,7 +42,7 @@
 
 
 class TDKStyle(Style):
-    """An attempt at creating a Pygments style similar to GitHub's pretty lights dark theme"""
+    """A Pygments style similar to GitHub's pretty lights dark theme"""
 
     background_color = "#0d1117"
     default_style = ''
@@ -123,6 +123,7 @@ class TDKStyle(Style):
         Punctuation: "#f8f8f2",
         Punctuation.Definition.Comment: pl["syntax-comment"],
         String: pl["syntax-string"],
+        String.Affix: pl["syntax-string"],
         String.Backtick: pl["syntax-string"],
         String.Char: pl["syntax-string"],
         String.Comment: pl["syntax-comment"],
diff --git a/sphinx_github_style/lexer.py b/sphinx_github_style/lexer.py
@@ -2,17 +2,17 @@
 from pathlib import Path
 from types import ModuleType
 from pygments.token import Name, Keyword
-from typing import Type, Optional, Set, Any
 from pygments.lexers.python import PythonLexer
+from typing import Type, Optional, Set, Any, Dict
 from inspect import getmembers, isfunction, ismethod, ismodule, isclass, isbuiltin, ismethoddescriptor
 
 
-def is_module_in_package(object, top_level):
+def is_module_in_package(object: Any, top_level: str) -> bool:
     """Predicate to determine if an object is a module within a top level package"""
     return ismodule(object) and object.__name__.startswith(top_level)
 
 
-def is_class_in_package(object, top_level):
+def is_class_in_package(object: Any, top_level: str) -> bool:
     """Predicate to determine if an object is a class within a top level package"""
     return isclass(object) and object.__module__.startswith(top_level)
 
@@ -59,8 +59,8 @@ def get_pkg_funcs(pkg_module: ModuleType, top_level: str, funcs_meths: Set[str]
     return funcs_meths
 
 
-def get_funcs_from_external_module(module: ModuleType, funcs_meths: Set[str]):
-    """Adds functions/methods contained within an imported external module"""
+def get_funcs_from_external_module(module: ModuleType, funcs_meths: Set[str]) -> Set[str]:
+    """Adds functions/methods contained directly within an imported external module"""
     funcs_meths.update(get_funcs(module))
     top_level = module.__name__
 
@@ -71,11 +71,13 @@ def get_funcs_from_external_module(module: ModuleType, funcs_meths: Set[str]):
 
 
 def get_funcs(of: Any) -> Set[str]:
+    """Returns the names of all members of the provided object that are functions or methods"""
     members = getmembers(of, lambda obj: isfunction(obj) or ismethod(obj))
     return set(dict(members))
 
 
-def get_builtins():
+def get_builtins() -> Dict[str, Set]:
+    """Returns a dictionary containing names of built-in functions, classes, and methods"""
     funcs_meths = set(dict(getmembers(builtins, isbuiltin)))
     classes = set()
 
@@ -93,10 +95,9 @@ def get_builtins():
 BUILTINS = get_builtins()
 
 
-class TDKMethLexer(PythonLexer):
-    """Adds syntax highlighting for methods and functions within a python Package
+class TDKLexer(PythonLexer):
+    """A Pygments Lexer that adds syntax highlighting for the methods, classes, type hints, etc. in a Python package"""
 
-    """
     name = 'TDK'
     url = 'https://github.com/TDKorn'
     aliases = ['tdk']
@@ -106,7 +107,11 @@ class TDKMethLexer(PythonLexer):
     CLASSES = BUILTINS['classes']
 
     @classmethod
-    def get_pkg_lexer(cls, pkg_name: Optional[str] = None) -> Type["TDKMethLexer"]:
+    def get_pkg_lexer(cls, pkg_name: Optional[str] = None) -> Type["TDKLexer"]:
+        """Returns a lexer capable of highlighting all funcs/methods/classes/type hints within the provided package
+
+        :param pkg_name: the name of the package's top-level module
+        """
         if pkg_name:
             cls.TOP_LEVEL = pkg_name
 
@@ -121,6 +126,7 @@ def get_pkg_lexer(cls, pkg_name: Optional[str] = None) -> Type["TDKMethLexer"]:
         return cls
 
     def get_tokens_unprocessed(self, text):
+        """Override to add better syntax highlighting"""
         tokens = list(PythonLexer.get_tokens_unprocessed(self, text))
 
         for token_idx, (index, token, value) in enumerate(tokens):
