changeset 1195:a52b5aa085da

merged
author Thomas Waldmann <tw AT waldmann-edv DOT de>
date Mon, 02 Jan 2012 05:17:46 +0100
parents 7fcca568fed1 (current diff) 5543dd64b1ee (diff)
children 8905bb8bcb5f
files
diffstat 6 files changed, 82 insertions(+), 61 deletions(-) [+]
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/_static/custom.css	Mon Jan 02 05:17:46 2012 +0100
@@ -0,0 +1,36 @@
+/* Custom CSS for Sphinx */
+
+/* Import the default theme's CSS file */
+@import "default.css";
+
+.bolditalic {
+    font-weight: bold;
+    font-style: italic;
+}
+
+.sub {
+    vertical-align: sub;
+    font-size: 50%;
+}
+
+.sup {
+    vertical-align: super;
+    font-size: 50%;
+}
+
+.strikethrough {
+    text-decoration: line-through;
+}
+
+.underline {
+    text-decoration: underline;
+}
+
+/* We need borders around each cell to clearly demonstrate table boundaries
+ * in markup documentation */
+table.docutils th,
+table.docutils td {
+    border-style: solid;
+    border-width: 1px;
+    border-color: #AAAAAA;
+}
--- a/docs/conf.py	Mon Jan 02 04:39:31 2012 +0100
+++ b/docs/conf.py	Mon Jan 02 05:17:46 2012 +0100
@@ -97,6 +97,11 @@
 # a list of builtin themes.
 html_theme = 'default'
 
+# The style sheet to use for HTML pages. A file of that name must exist either
+# in Sphinx’ static/ path, or in one of the custom paths given in
+# html_static_path. Default is the stylesheet given by the selected theme.
+html_style = 'custom.css'
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
--- a/docs/user/creolewiki.rst	Mon Jan 02 04:39:31 2012 +0100
+++ b/docs/user/creolewiki.rst	Mon Jan 02 05:17:46 2012 +0100
@@ -8,8 +8,6 @@
 
 Features currently not working with moin's rst parser are marked with **RSTTODO**.
 
-Features currently not working with moin's sphinx setup are marked with **SPHINXTODO**.
-
 Headings
 ========
 
@@ -67,13 +65,6 @@
 |                                     | | Second line                         | 
 +-------------------------------------+---------------------------------------+
 
-**SPHINXTODO** **RSTTODO**: Restructured Text cannot be both **bold** and *italic*. This is because bold and italic are simply
-treated as different levels of emphasis. It should be noted that this is a problem with the spec rather than Sphinx or Moin itself.
-
-It requires the following CSS to rectify: ::
-
-   .bolditalic{font-weight:bold;font-style:italic;}
-
 **RSTTODO**: Restructured Text line blocks are not working in Moin2
 
 Hyperlinks
--- a/docs/user/mediawiki.rst	Mon Jan 02 04:39:31 2012 +0100
+++ b/docs/user/mediawiki.rst	Mon Jan 02 05:17:46 2012 +0100
@@ -10,8 +10,6 @@
 
 Features currently not working with moin's rst parser are marked with **RSTTODO**.
 
-Features currently not working with moin's sphinx setup are marked with **SPHINXTODO**.
-
 Headings
 ========
 
@@ -76,13 +74,6 @@
 | | ``without '''markups'''</pre>``  | | ``without '''markups'''``        |
 +------------------------------------+------------------------------------+
 
-**SPHINXTODO**
-The following css is needed to display formatted text correctly: ::
-
- span.underline { text-decoration: underline; }
- span.strikethrough { text-decoration: line-through; }
- span.bolditalic { font-weight: bold; font-style: italic; }
-
 **RSTTODO**
 table headers are not formatted as headers
 (see "Tables" section for corresponding MWTODO)
--- a/docs/user/moinwiki.rst	Mon Jan 02 04:39:31 2012 +0100
+++ b/docs/user/moinwiki.rst	Mon Jan 02 05:17:46 2012 +0100
@@ -13,11 +13,6 @@
 
 Features currently not working with moin's Wiki parser are marked with **MOINTODO**.
 
-Features currently not working with moin's sphinx setup are marked with **SPHINXTODO**.
-
-
-**SPHINXTODO CSS**, the tables seem to have missing borders despite of the fact that the rst markup is correct.
-
 Table Of Contents
 =================
 
@@ -96,9 +91,6 @@
 | ``--(Stroke)--``                    | :strikethrough:`Stroke`               |
 +-------------------------------------+---------------------------------------+
 
-**Notes**:
- - **SPHINXTODO** Superscript, subscript and underline are not working in rst.
-
 Hyperlinks
 ==========
 
@@ -189,6 +181,12 @@
 Lists
 =====
 
+.. warning::
+   All Moin Wiki list syntax (including that for unordered lists, ordered lists and definition lists) requires a leading space before each item in the list.
+   Unfortunately, reStructuredText does not allow leading whitespace in code samples, so the example markup here will not work if copied verbatim, and requires
+   that each line of the list be indented by one space in order to be valid Moin Wiki markup.
+   This is also an **RSTTODO**
+
 Unordered Lists
 ---------------
 
@@ -290,11 +288,6 @@
    
  B. item 2
    
-**Notes**:
- - **SPHINXTODO** sphinx will remove the first space before every list item.
- - Moin increases the order number/roman/letter automaticaly. rst does not do any such thing, so i have to manually increase them here.
- - even the base level item has to have a space in the begining
-
 Definition Lists
 ================
 
@@ -310,8 +303,12 @@
  term
   definition
  object
-  description 1
-  description 2
+  | description 1
+  | description 2
+
+**Notes**:
+ - reStructuredText does not support multiple definitions for a single term, so a line break has been forced to illustrate the appearance of several definitions.
+   Using the prescribed Moin Wiki markup will, in fact, produce two separate definitions in MoinMoin (using separate ``<dd>`` tags).
   
 Tables
 ======
@@ -347,7 +344,7 @@
 
 **Notes**:
  - **MOINTODO:** the cell width does not work in moin 2.
- - **SPHINXTODO** rst does not support percentage cell width so cell has been made long manually
+ - reStructuredText does not support percentage cell width so cell has been made long manually. In MoinMoin the second cell will take up the maximum amount of horizontal space.
 
 Spanning Rows and Columns
 -------------------------
@@ -394,7 +391,7 @@
 +----------------+---------------------------------------+-------------------+
 
 **Notes**:
- - **SPHINXTODO** bottom align cannot be shown in rst.
+ - Text cannot be aligned in reStructuredText, but the text will appear as is described when used in MoinMoin.
 
 HTML-like Options for Tables
 ----------------------------
@@ -478,13 +475,15 @@
     print "Hello World!"
  }}}
  
-**Result**: ::
+**Result**:
 
- ---
- 
+.. code-block:: python
+
+    def hello():
+        print "Hello, world!"
+
 **Notes**:
  - The syntax crashes moin2.
- - **SPHINXTODO** The html required for the syntax box cannot be shown in rst.
 
 Using the wiki parser with css classes
 --------------------------------------
@@ -502,7 +501,7 @@
 +----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
 **Notes**:
- - **SPHINXTODO** The div cannot be shown in rst, so a table cell has been made to imitate it.
+ - The div cannot be shown in reStructuredText, so a table cell has been made to demonstrate the border produced. In MoinMoin, this border will appear red.
 
 Admonitions
 -----------
@@ -517,10 +516,10 @@
  
 **Result**:
 
----
+.. warning::
+    **Don't overuse admonitions**
 
-**Notes**:
- - **SPHINXTODO** The Admonition cannot be shown in rst.
+    Admonitions should be used with care. A page riddled with admonitions will look restless and will be harder to follow than a page where admonitions are used sparingly.
 
 Comments
 --------
@@ -535,8 +534,12 @@
  
 **Result**:
 
----
++--------------------------------------------------------------------------------+
+| This is a wiki parser section with class "comment dotted" (see HelpOnParsers). |
+|                                                                                |
+| Its visibility gets toggled the same way.                                      |
++--------------------------------------------------------------------------------+
 
 **Notes**:
- - **SPHINXTODO** The wiki parser section with class "comment dotted" cannot be shown in rst.
+ - reStructuredText has no support for dotted borders, so a table cell is used to illustrate the border which will be produced. This markup will actually produce a dotted border in MoinMoin.
  - The toggle display feature does not work yet
--- a/docs/user/rest.rst	Mon Jan 02 04:39:31 2012 +0100
+++ b/docs/user/rest.rst	Mon Jan 02 05:17:46 2012 +0100
@@ -6,11 +6,6 @@
 
 Features currently not working with moin's Wiki parser are marked with **RSTTODO**.
 
-Features currently not working with moin's sphinx setup are marked with **SPHINXTODO**.
-
-
-**SPHINXTODO CSS**, The tables are missing borders despite the fact that the rst markup is correct.
-
 Headings
 ========
 
@@ -206,26 +201,26 @@
 
  1. item 1
  
-   1. item 1.1
+    1. item 1.1
+    #. item 1.2
    
-   2. item 1.2
-   
- 2. item 2
+ #. item 2
 
 **Result**:
 
  1. item 1
  
-   1. item 1.1
+    1. item 1.1
+    #. item 1.2
    
-   2. item 1.2
-   
- 2. item 2
+ #. item 2
    
 **Notes**:
- - The order and the numbering agent have to be maintained by the user. Any character can be used to number the items (e.g. a/A or i/I).
- - **SPHINXTODO** sphinx will remove the first space before every list item.
- - even the base level item has to have a space in the beginning
+ - Ordered lists can be automatically enumerated using the ``#`` character as demonstrated above. Note that the first item of an ordered list
+   auto-enumerated in this fashion must use explicit numbering notation (e.g. ``1.``) in order to select the enumeration sequence type
+   (e.g. Roman numerals, Arabic numerals, etc.), initial number (for lists which do not start at "1") and formatting type (e.g. ``1.`` or ``(1)`` or ``1)``). More information on
+   enumerated lists can be found in the `reStructuredText documentation <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#enumerated-lists>`_.
+ - One or more blank lines are required before and after reStructuredText lists.
 
 Definition Lists
 ================