From 85e74fb710e64a35b3ed458bdec6cfed7827c3b1 Mon Sep 17 00:00:00 2001 From: Tiago Serafim Date: Wed, 19 Sep 2012 18:43:21 -0300 Subject: First version of the docs. --- docs/extensions/admonition.txt | 75 ++++++++++++++++++++++++++++++++++++++++ docs/extensions/code_hilite.txt | 46 ++++++++++++------------ docs/extensions/index.txt | 25 +++++++------- docs/extensions/smart_strong.txt | 6 ++-- 4 files changed, 114 insertions(+), 38 deletions(-) create mode 100644 docs/extensions/admonition.txt (limited to 'docs/extensions') diff --git a/docs/extensions/admonition.txt b/docs/extensions/admonition.txt new file mode 100644 index 0000000..48b70c8 --- /dev/null +++ b/docs/extensions/admonition.txt @@ -0,0 +1,75 @@ +title: Admonition +prev_title: Smart Strong Extension +prev_url: smart_strong.html +next_title: CodeHilite Extension +next_url: code_hilite.html + +Admonition +========== + +Summary +------- + +This extension adds [rST-style][rST] admonitions to Markdown documents. + +This extension is included in the standard Markdown library. + +[rST]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions + +Syntax +------ + +Admonitions are created using the following syntax: + + !!! [type] [optional explicit title within double quotes] + Any number of other indented markdown elements. + + This is the second paragraph. + +`type` will be used as the CSS classname and as default title. It must be a +single word. So, for instance: + + !!! note + You should note that the title will be automatically capitalized. + +will render: + +
+

Note

+

You should note that the title will be automatically capitalized.

+
+ +Optionally, you can use custom titles. For instance: + + !!! danger "Don't try this at home" + ... + +will render: + +
+

Don't try this at home

+

...

+
+ +If you don't want a title, use a blank string `""`: + + !!! important "" + This is a admonition box without a title. + +results in: + +
+

This is a admonition box without a title.

+
+ + +rST suggests the following `types`, but you're free to use whatever you want: + attention, caution, danger, error, hint, important, note, tip, warning. + +Styling +------- + +There is no CSS included as part of this extension. Look up the default +[Sphinx][sphinx] theme if you need inspiration. + +[sphinx]: http://sphinx.pocoo.org/ \ No newline at end of file diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt index 55a1a00..fbf05b3 100644 --- a/docs/extensions/code_hilite.txt +++ b/docs/extensions/code_hilite.txt @@ -1,6 +1,6 @@ title: CodeHilite Extension -prev_title: Smart Strong Extension -prev_url: smart_strong.html +prev_title: Admonition Extension +prev_url: admonition.html next_title: HTML Tidy Extension next_url: html_tidy.html @@ -10,7 +10,7 @@ CodeHilite Summary ------- -The CodeHilite Extension adds code/syntax highlighting to standard +The CodeHilite Extension adds code/syntax highlighting to standard Python-Markdown code blocks using [Pygments][]. [Pygments]: http://pygments.org/ @@ -20,32 +20,32 @@ This extension is included in the Markdown library. Setup ----- -You will also need to [download][dl] and install the Pygments package on your +You will also need to [download][dl] and install the Pygments package on your `PYTHONPATH`. You will need to determine the appropriate CSS classes and create -appropriate rules for them, which are either defined in or linked from the -header of your HTML templates. See the excellent [documentation][] for more -details. If no language is defined, Pygments will attempt to guess the +appropriate rules for them, which are either defined in or linked from the +header of your HTML templates. See the excellent [documentation][] for more +details. If no language is defined, Pygments will attempt to guess the language. When that fails, the code block will display as un-highlighted code. [dl]: http://pygments.org/download/ [documentation]: http://pygments.org/docs -**Note:** The css and/or javascript is not included as part of this extension +**Note:** The css and/or javascript is not included as part of this extension but shall always be provided by the end user. Syntax ------ -The CodeHilite Extension follows the same [syntax][] as regular Markdown code -blocks, with one exception. The hiliter needs to know what language to use for -the code block. There are three ways to tell the hiliter what language the code +The CodeHilite Extension follows the same [syntax][] as regular Markdown code +blocks, with one exception. The hiliter needs to know what language to use for +the code block. There are three ways to tell the hiliter what language the code block contains and each one has a different result. [syntax]: http://daringfireball.net/projects/markdown/syntax#precode ###SheBang (with path) -If the first line of the codeblock contains a shebang, the language is derived +If the first line of the codeblock contains a shebang, the language is derived from that and line numbers are used. #!/usr/bin/python @@ -59,8 +59,8 @@ Will result in: ###SheBang (no path) -If the first line contains a shebang, but the shebang line does not contain a -path (a single `/` or even a space), then that line is removed from the code +If the first line contains a shebang, but the shebang line does not contain a +path (a single `/` or even a space), then that line is removed from the code block before processing. Line numbers are used. #!python @@ -72,8 +72,8 @@ Will result in: ####Colons -If the first line begins with three or more colons, the text following the -colons identifies the language. The first line is removed from the code block +If the first line begins with three or more colons, the text following the +colons identifies the language. The first line is removed from the code block before processing and line numbers are not used. :::python @@ -85,10 +85,10 @@ Will result in: ###When No Language is Defined -CodeHilite is completely backward compatible so that if a code block is -encountered that does not define a language, the block is simple wrapped in -`
` tags and output. Note: one exception would be that the Pygments 
-highlighting engine will try to guess the language. Upon failure, the same 
+CodeHilite is completely backward compatible so that if a code block is
+encountered that does not define a language, the block is simple wrapped in
+`
` tags and output. Note: one exception would be that the Pygments
+highlighting engine will try to guess the language. Upon failure, the same
 behavior will happen as described here.
 
         # Code goes here ...
@@ -109,11 +109,11 @@ From the Python interpreter:
 
     >>> html = markdown.markdown(text, ['codehilite'])
 
-If you want every code block to have line numbers, even when using colons 
-(`:::`) for language identification, the setting `force_linenos` is available 
+If you want every code block to have line numbers, even when using colons
+(`:::`) for language identification, the setting `force_linenos` is available
 to do so.
 
-    >>> html = markdown.markdown(text, 
+    >>> html = markdown.markdown(text,
     ...     ['codehilite(force_linenos=True)']
     ... )
 
diff --git a/docs/extensions/index.txt b/docs/extensions/index.txt
index 82b0eda..610fe21 100644
--- a/docs/extensions/index.txt
+++ b/docs/extensions/index.txt
@@ -8,16 +8,16 @@ next_url:   extra.html
 Available Extensions
 ====================
 
-Python Markdown offers a flexible extension mechanism, which makes it possible 
-to change and/or extend the behavior of the parser without having to edit the 
-actual source files. 
+Python Markdown offers a flexible extension mechanism, which makes it possible
+to change and/or extend the behavior of the parser without having to edit the
+actual source files.
 
 To use an extension, pass it's name to markdown with the `extensions` keyword.
-See the [Library Reference](../reference.html#extensions) for more details. 
+See the [Library Reference](../reference.html#extensions) for more details.
 
     markdown.markdown(some_text, extensions=['extra', 'nl2br'])
 
-From the command line, specify an extension with the `-x` option. See the 
+From the command line, specify an extension with the `-x` option. See the
 [Command Line docs](../cli.html) or use the `--help` option for more details.
 
     python -m markdown -x extra input.txt > output.html
@@ -26,9 +26,9 @@ Officially Supported Extensions
 -------------------------------
 
 The extensions listed below are included with (at least) the most recent release
-and are officially supported by Python-Markdown. Any documentation is 
-maintained here and all bug reports should be made to the project. If you 
-have a typical install of Python-Markdown, these extensions are already 
+and are officially supported by Python-Markdown. Any documentation is
+maintained here and all bug reports should be made to the project. If you
+have a typical install of Python-Markdown, these extensions are already
 available to you.
 
 * [Extra](extra.html)
@@ -39,6 +39,7 @@ available to you.
     * [Footnotes](footnotes.html)
     * [Tables](tables.html)
     * [Smart Strong](smart_strong.html)
+* [Admonition](admonition.html)
 * [CodeHilite](code_hilite.html)
 * [HTML Tidy](html_tidy.html)
 * [HeaderId](header_id.html)
@@ -53,11 +54,11 @@ Third Party Extensions
 ----------------------
 
 Various individuals and/or organizations have developed extensions which they
-have made available to the public.  A [list of third party 
+have made available to the public.  A [list of third party
 extensions](https://github.com/waylan/Python-Markdown/wiki/Third-Party-Extensions)
-is maintained on the wiki for your convenience. The Python-Markdown team 
-offers no official support for these extensions. Please see the developer of 
+is maintained on the wiki for your convenience. The Python-Markdown team
+offers no official support for these extensions. Please see the developer of
 each extension for support.
 
-If you would like to write your own extensions, see the 
+If you would like to write your own extensions, see the
 [Extensions API](api.html) for details.
diff --git a/docs/extensions/smart_strong.txt b/docs/extensions/smart_strong.txt
index 8de574f..fd3bae6 100644
--- a/docs/extensions/smart_strong.txt
+++ b/docs/extensions/smart_strong.txt
@@ -1,8 +1,8 @@
 title:      Smart Strong Extension
 prev_title: Tables Extension
 prev_url:   tables.html
-next_title: CodeHilite Extension
-next_url:   code_hilite.html
+next_title: Admonition Extension
+next_url:   admonition.html
 
 Smart_Strong
 ============
@@ -11,7 +11,7 @@ Summary
 -------
 
 The Markdown Smart_Strong Extension adds smarter handling of double underscores
-within words. This does for double underscores what 
+within words. This does for double underscores what
 [smart_emphasis](../reference.html#smart_emphasis) does for single underscores.
 
 The Smart_Strong Extension is included in the standard Markdown library.
-- 
cgit v1.2.3