Docs fixes (#84)

* Set column width for CLI help

* Update mkdocs and mkdocstrings configurations

* Fix config docstrings

* Fix reprexes dataclass docstrings

* Bump lockfile

---------

Co-authored-by: Jay Qi <jayqi@users.noreply.github.com>

Author: jayqi

docs/docs/css/extra.css

@@ -12,36 +12,3 @@ th.no-wrap,
 td.no-wrap {
     white-space: nowrap;
 }
-
-
-/* mkdocstrings custom style */
-
-.doc.doc-heading {
-    padding-left: 1ch;
-    padding-bottom: 5px;
-    background-color: #F8F8F8;
-}
-
-div.doc-contents:not(.first) {
-    padding-left: 2ch;
-}
-
-/* Class name headings */
-h3.doc.doc-heading>code {
-    font-weight: bold;
-}
-
-/* Class attribute and method headings */
-h5.doc.doc-heading {
-    font-size: 1em;
-    text-transform: none;
-}
-
-/* Bold function, method, and attribute names */
-.doc.doc-heading span {
-    font-weight: bold;
-}
-
-.doc.doc-heading span~span {
-    font-weight: normal;
-}

docs/mkdocs.yml

@@ -32,20 +32,29 @@ theme:
   logo: images/reprexlite.svg
   favicon: images/reprexlite_white_blue.svg
   palette:
-    # Palette toggle for dark mode
-    - scheme: slate
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
       primary: indigo
       accent: blue
       toggle:
-        icon: material/brightness-4
+        icon: material/brightness-auto
         name: Switch to light mode
     # Palette toggle for light mode
-    - scheme: default
+    - media: "(prefers-color-scheme: light)"
       primary: indigo
       accent: blue
+      scheme: default
       toggle:
         icon: material/brightness-7
         name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      primary: indigo
+      accent: blue
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
   custom_dir: overrides/
 
 extra_css:
@@ -75,20 +84,24 @@ plugins:
         python:
           paths: [../reprexlite]
           options:
+            # General
+            docstring_style: google
             # Headings options
             heading_level: 2
             show_root_toc_entry: false
             show_root_full_path: false
             show_root_heading: false
             show_category_heading: true
             # Members options
-            filters: ["!^_(?!_init__)"]
-            group_by_category: true
-            inherited_members: true
+            filters: ["!^_", "^__init__$"]
             # Docstrings options
             show_if_no_docstring: false
+            merge_init_into_class: true
             # Signatures/annotation options
+            annotations_path: brief
+            separate_signature: true
             show_signature_annotations: true
+            unwrap_annotated: true
             # Additional options
             show_source: true
   - mike:

justfile

@@ -45,7 +45,7 @@ _docs-preprocess:
     @echo '```' >> docs/docs/cli.md
     @echo "" >> docs/docs/cli.md
     @echo '```' >> docs/docs/cli.md
-    @uv run reprex --help >> docs/docs/cli.md
+    @COLUMNS=80 uv run reprex --help >> docs/docs/cli.md
     @echo '```' >> docs/docs/cli.md
     sed 's|https://raw.githubusercontent.com/jayqi/reprexlite/main/docs/docs/images/demo.gif|images/demo.gif|g' README.md \
         | sed 's|https://jayqi.github.io/reprexlite/stable/||g' \

reprexlite/config.py

@@ -14,7 +14,7 @@
 class ParsingMethod(str, Enum):
     """Methods for parsing input strings.
 
-    Args:
+    Attributes:
         AUTO (str): Automatically identify reprex-style or doctest-style input.
         DECLARED (str): Use configured values for parsing.
     """
@@ -24,7 +24,17 @@ class ParsingMethod(str, Enum):
 
 
 class Venue(str, Enum):
-    """Enum for specifying the output venue for a reprex."""
+    """Enum for specifying the output venue for a reprex.
+
+    Attributes:
+        GH (str): GitHub-flavored Markdown
+        DS (str): Discourse
+        SO (str): StackOverflow
+        HTML (str): HTML
+        PY (str): Python script
+        RTF (str): Rich Text Format
+        SLACK (str): Slack markup
+    """
 
     GH = "gh"
     DS = "ds"
@@ -41,9 +51,9 @@ class ReprexConfig:
     formatting.
 
     Args:
-        editor (str): Command-line program name of editor to use. If not specified, check $EDITOR
-            and $VISUAL environment variables. If 'ipython', will launch the IPython interactive
-            editor.
+        editor (Optional[str]): Command-line program name of editor to use. If not specified,
+            check $EDITOR and $VISUAL environment variables. If 'ipython', will launch the IPython
+            interactive editor.
         venue (str): Key to identify the output venue that the reprex will be shared in. Used to
             select an appropriate formatter. See "Venues Formatting" documentation for formats
             included with reprexlite.

reprexlite/reprexes.py

@@ -26,7 +26,7 @@ class RawResult:
     """Class that holds the result of evaluated code. Use `str(...)` on an instance to produce a
     pretty-formatted comment block representation of the result.
 
-    Attributes:
+    Args:
         config (ReprexConfig): Configuration for formatting and parsing
         raw (Any): Some Python object that is the raw return value of evaluated Python code.
         stdout (str): Standard output from evaluated Python code.
@@ -69,7 +69,7 @@ def __eq__(self, other: Any) -> bool:
 class ParsedResult:
     """Class that holds parsed result from reading a reprex.
 
-    Attributes:
+    Args:
         config (ReprexConfig): Configuration for formatting and parsing
         lines (List[str]): String content of result parsed from a reprex
     """
@@ -115,7 +115,7 @@ def __eq__(self, other: Any) -> bool:
 class Statement:
     """Dataclass that holds a LibCST parsed statement. of code.
 
-    Attributes:
+    Args:
         config (ReprexConfig): Configuration for formatting and parsing
         stmt (Union[libcst.SimpleStatementLine, libcst.BaseCompoundStatement]): LibCST parsed
             statement.
@@ -227,7 +227,7 @@ def __eq__(self, other: Any) -> bool:
 class Reprex:
     """Dataclass for a reprex, which holds Python code and results from evaluation.
 
-    Attributes:
+    Args:
         config (ReprexConfig): Configuration for formatting and parsing
         statements (List[Statement]): List of parsed Python code statements
         results (List[RawResult]): List of results evaluated from statements