changeset 1189:8e85da9cfb7b

Fix all the SPHINXTODOs in docs/
author Sam Toyer <samATqxcvDOTnet>
date Tue, 27 Dec 2011 23:43:56 +1000
parents 3cb39729ee3d
children 3b97bf57f6af
files docs/_static/custom.css docs/conf.py docs/user/creolewiki.rst docs/user/mediawiki.rst docs/user/moinwiki.rst docs/user/rest.rst
diffstat 6 files changed, 69 insertions(+), 50 deletions(-) [+]
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/_static/custom.css	Tue Dec 27 23:43:56 2011 +1000
@@ -0,0 +1,44 @@
+/* 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;
+}
+
+.border-red {
+    border-color: red;
+}
+
+.border-dotted {
+    border-style: dotted;
+}
--- a/docs/conf.py	Sun Dec 25 03:49:39 2011 +0100
+++ b/docs/conf.py	Tue Dec 27 23:43:56 2011 +1000
@@ -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	Sun Dec 25 03:49:39 2011 +0100
+++ b/docs/user/creolewiki.rst	Tue Dec 27 23:43:56 2011 +1000
@@ -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	Sun Dec 25 03:49:39 2011 +0100
+++ b/docs/user/mediawiki.rst	Tue Dec 27 23:43:56 2011 +1000
@@ -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	Sun Dec 25 03:49:39 2011 +0100
+++ b/docs/user/moinwiki.rst	Tue Dec 27 23:43:56 2011 +1000
@@ -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
 ==========
 
@@ -226,6 +218,7 @@
    
 **Note**:
  - moin markup allows a square, white and a bulletless item for unordered lists, these cannot be chosen in rst
+ - One or more blank lines are required before and after lists using the Moin Wiki syntax.
 
 Ordered Lists
 ---------------
@@ -290,11 +283,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
 ================
 
@@ -347,7 +335,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 +382,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 +466,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 +492,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 +507,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 +525,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	Sun Dec 25 03:49:39 2011 +0100
+++ b/docs/user/rest.rst	Tue Dec 27 23:43:56 2011 +1000
@@ -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
 ========
 
@@ -224,8 +219,7 @@
    
 **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
+ - One or more blank lines are required before and after reStructuredText lists.
 
 Definition Lists
 ================