From 75dee451b1902e95b91c97f998af4c38e4ce670a Mon Sep 17 00:00:00 2001 From: gbrandl Date: Fri, 12 Jan 2007 22:53:02 +0100 Subject: [svn] Generate lexer, formatter and filter docs from docstrings. There is the problem of ordering, though. --- pygments/filters/__init__.py | 12 ++- pygments/formatters/__init__.py | 8 +- pygments/formatters/bbcode.py | 19 ++-- pygments/formatters/html.py | 131 ++++++++++++++++------ pygments/formatters/latex.py | 62 +++++++---- pygments/formatters/other.py | 16 +-- pygments/formatters/rtf.py | 14 ++- pygments/formatters/terminal.py | 30 +++--- pygments/lexers/agile.py | 62 +++++++++-- pygments/lexers/compiled.py | 29 ++++- pygments/lexers/dotnet.py | 17 ++- pygments/lexers/other.py | 17 ++- pygments/lexers/special.py | 11 +- pygments/lexers/templates.py | 234 +++++++++++++++++++++++++++++++++++++--- pygments/lexers/text.py | 52 ++++++++- pygments/lexers/web.py | 50 ++++++++- 16 files changed, 639 insertions(+), 125 deletions(-) (limited to 'pygments') diff --git a/pygments/filters/__init__.py b/pygments/filters/__init__.py index 3f42741f..3bf7d79a 100644 --- a/pygments/filters/__init__.py +++ b/pygments/filters/__init__.py @@ -41,7 +41,10 @@ def get_all_filters(): class CodeTagFilter(Filter): """ - Highlights codetags in comments and docstrings. + Highlights special code tags in comments and docstrings. Per default, the + list of highlighted tags is ``XXX``, ``TODO``, ``BUG`` and ``NOTE``. You can + override this list by specifying a `codetags` parameter that takes a list of + words. """ def __init__(self, **options): Filter.__init__(self) @@ -72,8 +75,11 @@ class CodeTagFilter(Filter): class KeywordCaseFilter(Filter): """ - Changes the case of keywords. (To ``lower``, ``upper`` or - ``capitalize`` case) + Converts keywords to ``lower``, ``upper`` or ``capitalize`` which means + first letter uppercase, rest lowercase. This can be useful e.g. if you + highlight Pascal code and want to adapt the code to your styleguide. The + default is ``lower``, override that by providing the `keywordcase` + parameter. """ def __init__(self, **options): diff --git a/pygments/formatters/__init__.py b/pygments/formatters/__init__.py index be20c0ce..8aefe103 100644 --- a/pygments/formatters/__init__.py +++ b/pygments/formatters/__init__.py @@ -34,18 +34,18 @@ def _doc_desc(obj): FORMATTERS = { HtmlFormatter: ('HTML', ('html',), ('.htm', '.html'), _doc_desc(HtmlFormatter)), - TerminalFormatter: ('Terminal', ('terminal', 'console'), (), - _doc_desc(TerminalFormatter)), LatexFormatter: ('LaTeX', ('latex', 'tex'), ('.tex',), _doc_desc(LatexFormatter)), RtfFormatter: ('RTF', ('rtf',), ('.rtf',), _doc_desc(RtfFormatter)), + TerminalFormatter: ('Terminal', ('terminal', 'console'), (), + _doc_desc(TerminalFormatter)), + BBCodeFormatter: ('BBcode', ('bbcode', 'bb'), (), + _doc_desc(BBCodeFormatter)), RawTokenFormatter: ('Raw tokens', ('raw', 'tokens'), ('.raw',), _doc_desc(RawTokenFormatter)), NullFormatter: ('Text only', ('text', 'null'), ('.txt',), _doc_desc(NullFormatter)), - BBCodeFormatter: ('BBcode', ('bbcode', 'bb'), (), - _doc_desc(BBCodeFormatter)) } diff --git a/pygments/formatters/bbcode.py b/pygments/formatters/bbcode.py index d9b96485..2f15884a 100644 --- a/pygments/formatters/bbcode.py +++ b/pygments/formatters/bbcode.py @@ -18,12 +18,14 @@ __all__ = ['BBCodeFormatter'] class BBCodeFormatter(Formatter): """ - Output BBCode tags with appropiate colors and formatting. + Formats tokens with BBcodes. These formatting codes are used by many + bulletin boards, so you can highlight your sourcecode with pygments before + posting it there. - This formatter doesn't support background colors and borders, as there are - no common BBcodes for that. + This formatter has no support for background colors and borders, as there + are no common BBcode tags for that. - Some board systems (e.g. phpBB) don't support markup in their [code] tag, + Some board systems (e.g. phpBB) don't support colors in their [code] tag, so you can't use the highlighting together with that tag. Text in a [code] tag usually is shown with a monospace font (which this formatter can do with the ``monofont`` option) and no spaces (which you @@ -31,12 +33,13 @@ class BBCodeFormatter(Formatter): Additional options accepted: - ``codetag`` - If set to true, put the output into [code] tags (default: false). + `codetag` + If set to true, put the output into ``[code]`` tags (default: + ``false``) - ``monofont`` + `monofont` If set to true, add a tag to show the code with a monospace font - (default: false). + (default: ``false``). """ def __init__(self, **options): diff --git a/pygments/formatters/html.py b/pygments/formatters/html.py index f72046ef..d323c781 100644 --- a/pygments/formatters/html.py +++ b/pygments/formatters/html.py @@ -103,43 +103,106 @@ td.linenos { background-color: #f0f0f0; padding-right: 10px; } class HtmlFormatter(Formatter): """ - Output HTML tags with appropriate classes. + Format tokens as HTML 4 ```` tags within a ``
`` tag, wrapped
+    in a ``
`` tag. The ``
``'s CSS class can be set by the `cssclass`
+    option.
+
+    If the `linenos` option is given and true, the ``
`` is additionally
+    wrapped inside a ```` which has one row and two cells: one
+    containing the line numbers and one containing the code. Example:
+
+    .. sourcecode:: html
+
+        

+        

+          
+          
+        

+            
1
+            2

+          		
+            
def foo(bar):
+              pass
+            

+          

+
+    (whitespace added to improve clarity). Wrapping can be disabled using the
+    `nowrap` option.
+
+    With the `full` option, a complete HTML 4 document is output, including
+    the style definitions inside a ``