Implement 6 out of 7 TODO.md items: chart titles, plain output, compilation validation, lexers with documentation integration, and improved warmup

TODO.md

@@ -1,7 +1,7 @@
 # TODO
 
-- [ ] Maybe custom timeit implementation, especially for warmups, since they don't mean anything currently
-- [ ] Add a `--plain` option
+- [x] Maybe custom timeit implementation, especially for warmups, since they don't mean anything currently
+- [x] Add a `--plain` option
   - For this, we can use the ipython syntax
 
     ```text
@@ -10,15 +10,15 @@
 
     Where loop means run and runs means batches in fastero talk
 
-- [ ] Find/write an asciidoc lexer for pygments
-- [ ] Maybe find/write a better shell lexer for shell syntax
-  - [ ] Should make `--option` dimmed
-  - [ ] Should make the first word some color
-  - [ ] Should make strings some color
-- [ ] Test compile the code using the `compile()` function before benchmarking. This should be done so that
+- [x] Find/write an asciidoc lexer for pygments
+- [x] Maybe find/write a better shell lexer for shell syntax
+  - [x] Should make `--option` dimmed
+  - [x] Should make the first word some color
+  - [x] Should make strings some color
+- [x] Test compile the code using the `compile()` function before benchmarking. This should be done so that
       any syntax errors can be caught before benchmarking multiple snippets [for a long time] and then it all
       going to waste because of the last snippet having some problem.
-- [ ] Support adding titles to pots generated using matplotlib. This is really easy to implement.
+- [x] Support adding titles to pots generated using matplotlib. This is really easy to implement.
       There should be some parameter, preferably `--chart-title` and then it's value can then be passed
       on to the export_plot function which then, in turn, would use `plt.title(x)` where x is the title.
 - [ ] Allow specifying which lines to benchmark with the `file:` directive. change documentation to reflect this feature

docs/source/asciidoc_lexer.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python
+# @Author: Arian Mollik Wasi
+# @Date: 2024-08-20
+# @Description: AsciiDoc lexer for Pygments
+"""Pygments AsciiDoc Lexer asciidoc_lexer/asciidoc.py
+
+    * http://pygments.org/docs/lexerdevelopment/
+    * https://asciidoc.org/
+"""
+from __future__ import print_function
+
+from pygments.lexer import RegexLexer, bygroups, include
+from pygments.token import (
+    Keyword, Literal, Name, Operator, Punctuation, Generic, Text, 
+    Comment, String, Number, Error
+)
+
+class AsciiDocLexer(RegexLexer):
+    """Simple AsciiDoc lexer for Pygments.
+
+    Extends:
+        pygments.lexer.RegexLexer
+
+    Class Variables:
+        name {str} -- name of lexer
+        aliases {list} – languages, against whose GFM block names AsciiDocLexer will apply
+        filenames {list} – file name patterns, for whose contents AsciiDocLexer will apply
+        tokens {dict} – regular expressions internally matching AsciiDoc's components
+    """
+
+    name = 'AsciiDoc'
+    aliases = ['asciidoc', 'adoc']
+    filenames = ['*.asciidoc', '*.adoc', '*.asc']
+    mimetypes = ['text/asciidoc']
+
+    tokens = {
+        'root': [
+            # Document title (level 0)
+            (r'^= .+$', Generic.Heading),
+
+            # Section titles (levels 1-5)
+            (r'^={2,6} .+$', Generic.Subheading),
+
+            # Comments
+            (r'^//.*$', Comment.Single),
+
+            # Block delimiters
+            (r'^-{4,}$', Punctuation),
+            (r'^={4,}$', Punctuation),
+            (r'^\.{4,}$', Punctuation),
+            (r'^\*{4,}$', Punctuation),
+            (r'^\+{4,}$', Punctuation),
+            (r'^_{4,}$', Punctuation),
+
+            # Attributes
+            (r'^:([^:]+):\s*(.*)$', bygroups(Name.Attribute, String)),
+
+            # Lists
+            # Unordered lists
+            (r'^\s*(\*+)\s+(.+)$', bygroups(Operator, Text)),
+            # Ordered lists  
+            (r'^\s*(\.\s*)+(.+)$', bygroups(Operator, Text)),
+            # Definition lists
+            (r'^(.+)::\s*$', Name.Tag),
+            (r'^\s+(.+)$', Text),
+
+            # Tables
+            (r'^\|={3,}$', Punctuation),
+            (r'^\|(.*)$', bygroups(Generic.Strong)),
+
+            # Block titles
+            (r'^\.[A-Za-z].*$', Name.Decorator),
+
+            # Inline formatting
+            # Bold
+            (r'\*([^*\n]+)\*', Generic.Strong),
+            # Italic  
+            (r'_([^_\n]+)_', Generic.Emph),
+            # Monospace
+            (r'`([^`\n]+)`', Literal),
+            # Superscript
+            (r'\^([^^]+)\^', Generic.Emph),
+            # Subscript  
+            (r'~([^~]+)~', Generic.Emph),
+
+            # Links
+            (r'(https?://[^\s\[\]]+)(\[[^\]]*\])?', bygroups(Name.Variable, String)),
+            (r'(mailto:[^\s\[\]]+)(\[[^\]]*\])?', bygroups(Name.Variable, String)),
+            (r'<<([^,>]+)(,[^>]*)?>>', bygroups(Name.Variable, String)),
+
+            # Images
+            (r'image:([^\[\s]+)(\[[^\]]*\])', bygroups(Name.Variable, String)),
+
+            # Macros
+            (r'([a-zA-Z0-9_-]+):([^\[\s]+)(\[[^\]]*\])', bygroups(Keyword, Name.Variable, String)),
+
+            # Passthroughs
+            (r'\+{3}(.+?)\+{3}', Literal),
+            (r'\${2}(.+?)\${2}', Literal),
+
+            # Line breaks and spaces
+            (r'\s+', Text),
+
+            # Everything else
+            (r'.', Text),
+        ]
+    }
+
+
+# Sample AsciiDoc content for testing
+sample_asciidoc = """
+= Document Title
+:author: John Doe
+:email: john.doe@example.com
+
+== Introduction
+
+This is a *bold* text and this is _italic_ text.
+You can also use `monospace` text.
+
+=== Code Example
+
+----
+def hello_world():
+    print("Hello, World!")
+----
+
+=== Lists
+
+* First item
+* Second item
+  ** Sub-item
+  ** Another sub-item
+
+. Numbered item
+. Another numbered item
+
+Definition Term:: 
+    This is the definition of the term.
+
+=== Links and Images
+
+Check out https://asciidoc.org[AsciiDoc] for more information.
+
+image:logo.png[Company Logo]
+
+=== Table
+
+|===
+|Name |Age |Location
+
+|John
+|30
+|New York
+
+|Jane
+|25
+|London
+|===
+"""
+
+if __name__ == '__main__':
+    # Test the lexer
+    from pygments import highlight
+    from pygments.formatters import TerminalFormatter
+
+    lexer = AsciiDocLexer()
+    formatter = TerminalFormatter()
+    result = highlight(sample_asciidoc, lexer, formatter)
+    print(result)

docs/source/conf.py

@@ -32,8 +32,15 @@
 from pygments import token
 from sphinx.highlighting import lexers
 from csv_lexer import CsvLexer
+from asciidoc_lexer import AsciiDocLexer
+from shell_lexer import ImprovedShellLexer
 
 lexers['csv'] = CsvLexer(startinline=True)
+lexers['asciidoc'] = AsciiDocLexer(startinline=True)
+lexers['adoc'] = AsciiDocLexer(startinline=True)
+lexers['shell'] = ImprovedShellLexer(startinline=True)
+lexers['bash'] = ImprovedShellLexer(startinline=True)
+lexers['improved-shell'] = ImprovedShellLexer(startinline=True)
 
 # -- General configuration ---------------------------------------------------
 

docs/source/index.rst

@@ -43,6 +43,7 @@ Fastero
    development/internal_structure
    development/workflows
    development/license
+   lexer_examples
 
 .. toctree::
    :hidden:
@@ -71,6 +72,7 @@ Indices and Tables
    * `Internal Structure <./development/internal_structure.html>`_
    * `License <./development/license.html>`_
    * `Workflows <./development/workflows.html>`_
+   * `Lexer Examples <./lexer_examples.html>`_
 * `Other <https://www.youtube.com/watch?v=dQw4w9WgXcQ>`_
    * `Glossary <./glossary.html>`_
    * `Index <./genindex.html>`_

docs/source/lexer_examples.rst

@@ -0,0 +1,98 @@
+##################
+Lexer Examples
+##################
+
+.. meta::
+   :description: Examples showing the enhanced syntax highlighting for shell and AsciiDoc content
+   :author: Arian Mollik Wasi
+   :copyright: Arian Mollik Wasi
+
+This page demonstrates the enhanced syntax highlighting provided by the custom lexers for shell commands and AsciiDoc content in fastero documentation.
+
+Enhanced Shell Highlighting
+---------------------------
+
+The improved shell lexer provides better syntax highlighting for fastero commands:
+
+.. code-block:: shell
+
+    # Install fastero with dependencies
+    pip install "fastero[export]"
+
+    # Run a simple benchmark
+    fastero "sum([1,2,3])" "sum((1,2,3))" --runs 10 --export-json results.json
+
+    # Use python module syntax
+    python -m fastero "len('hello')" --plain --warmup 5
+
+.. code-block:: bash
+
+    # More complex example with multiple options
+    fastero \
+        "list(range(100))" \
+        "tuple(range(100))" \
+        --runs 25 \
+        --export-plot chart.png \
+        --chart-title "List vs Tuple Performance" \
+        --export-csv results.csv \
+        --export-asciidoc results.adoc
+
+AsciiDoc Syntax Highlighting
+----------------------------
+
+The AsciiDoc lexer provides proper highlighting for AsciiDoc content:
+
+.. code-block:: asciidoc
+
+    = Fastero Benchmark Results
+    :author: Benchmark Runner
+    :email: runner@example.com
+
+    == Performance Comparison
+
+    This document contains *performance* results from _fastero_ benchmarks.
+
+    === Results Table
+
+    [cols=",,,,,,," options="header"]
+    |===
+    |Snippet Code|Snippet Name|Runs|Mean|Median|Min|Max|Standard Deviation
+    |str(1)|Benchmark 1|20000000|136.5 ns|134.7 ns|134.1 ns|147.7 ns|4.2 ns
+    |f'{1}'|Benchmark 2|55000000|54.9 ns|55.1 ns|53.4 ns|56.3 ns|1.0 ns
+    |===
+
+    === Key Findings
+
+    * `f-strings` are significantly faster than `str()` conversion
+    * The performance difference is ~2.5x in this test
+    * Both approaches have very low standard deviation
+
+    === Links and References
+
+    See the https://fastero.readthedocs.io[fastero documentation] for more details.
+
+    image:chart.png[Performance Chart]
+
+Features Demonstrated
+---------------------
+
+**Shell Lexer Features:**
+
+* **Command highlighting**: Commands like `fastero`, `python`, `pip` are highlighted
+* **Dimmed options**: CLI flags like `--runs`, `--export-json`, `-m` are dimmed for better visual hierarchy
+* **String highlighting**: Quoted arguments are properly colored
+* **File path recognition**: File extensions and paths are highlighted
+* **Line continuation**: Backslash continuations are handled correctly
+
+**AsciiDoc Lexer Features:**
+
+* **Document structure**: Headers with `=` are properly highlighted
+* **Attributes**: Document attributes like `:author:` are highlighted
+* **Inline formatting**: *bold*, _italic_, and `monospace` text
+* **Tables**: Table syntax including headers and separators
+* **Lists**: Both bullet and numbered lists
+* **Links**: URL and cross-reference linking
+* **Images**: Image inclusion syntax
+* **Code blocks**: Inline code with backticks
+
+Both lexers integrate seamlessly with Sphinx's documentation generation system and provide enhanced readability for fastero's documentation.