|
|
{{TableOfContents}}
|
|
This page describes the mapping from tbwiki markup language to reStructuredText
for the conversion of documentation to Sphynx and readthedocs. (see Issue_0046)
|
This page describes the mapping from tbwiki markup language to reStructuredText
for the conversion of documentation to Sphynx and readthedocs. (see [[Issue_0046]])
|
|
http://bird.org/tbwiki/TBWikiDocumentation
* ReStructuredText:
* RST cheat-sheet: https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
* Reference: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
* Quickref: https://docutils.sourceforge.io/docs/user/rst/quickref.html
|
= references =
* TBWIKI:
* http://bird.org/tbwiki/TBWikiDocumentation
* ReStructuredText:
* RST cheat-sheet: https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
* Reference: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
* Quickref: https://docutils.sourceforge.io/docs/user/rst/quickref.html
|
|
|
= mapping =
== headers ==
{{{
|
|
item | tbwiki | reStructuredText
____________________|_____________________|____________________
| |
| | ##########
Page Title | | Title
| | ##########
____________________|_____________________|____________________
| | =========
1st level heading | = Heading 1 = | Heading 1
| | =========
____________________|_____________________|____________________
| |
2nd level heading | == heading 2 == | Heading 2
| | =========
____________________|_____________________|____________________
| |
3rd level heading | === Heading 3 === | Heading 3
| | ---------
____________________|_____________________|____________________
| |
4th level heading | ==== Heading 4 ==== | Heading 4
| | ~~~~~~~~~
____________________|_____________________|____________________
| |
|
item | tbwiki | reStructuredText
____________________|_____________________|____________________
| |
| | ##########
Page Title | | Title
| | ##########
____________________|_____________________|____________________
| | =========
1st level heading | = Heading 1 = | Heading 1
| | =========
____________________|_____________________|____________________
| |
2nd level heading | == heading 2 == | Heading 2
| | =========
____________________|_____________________|____________________
| |
3rd level heading | === Heading 3 === | Heading 3
| | ---------
____________________|_____________________|____________________
| |
4th level heading | ==== Heading 4 ==== | Heading 4
| | ~~~~~~~~~
____________________|_____________________|____________________
| |
|
|
}}}
|
}}}
|
|
In rst, Heading order must be consistent, and you can't skip headings.
For example, you can't do H1 followed by H3. You must be consistent
with the heading underline styles. Sphinx autodetects the level associated
with the headings styles, so if you skip a style or use it differently
it will cause errors.
|
In rst, Heading order must be consistent, and you can't skip headings.
For example, you can't do H1 followed by H3. You must be consistent
with the heading underline styles. Sphinx autodetects the level associated
with the headings styles, so if you skip a style or use it differently
it will cause errors.
|
|
|
== inline markup ==
{{{
|
item | tbwiki | reStructuredText
_________________|___________________|____________________
| |
bold | '''bold''' | **bold**
| |
italic | ''italic'' | *italic*
| |
external link | http://foo | http://foo
| |
heading anchor | (automatic) | .. _name:
| | (automatic with sphinx.ext.autosectionlabel configured)
| |
| |
explicit anchor | Page Name | :doc:`page_name`
| |
| |
| |
bullet | * item | * item
| (first level must | (first level must follow an empty line)
| be indented) |
| |
dir or filename | filename | filename
| |
command | 'command' | command
|(no markup, but |
| convention was |
| single quotes) |
}}}
|
item | tbwiki | reStructuredText
_________________|___________________|____________________
| |
bold | '''bold''' | **bold**
| |
italic | ''italic'' | *italic*
| |
external link | http://foo | http://foo
| |
heading anchor | (automatic) | .. _name:
| | (automatic with sphinx.ext.autosectionlabel configured)
| |
| |
explicit anchor | {{HTML(<a name="#<name></a>)}} | .._name:
| |
| |
| |
page link | [[Page Name]] | :doc:`page_name`
| |
| |
| |
bullet | * item | * item
| (first level must | (first level must follow an empty line)
| be indented) |
| |
dir or filename | ``filename`` | ``filename``
| |
command | 'command' | ``command``
|(no markup, but |
| convention was |
| single quotes) |
}}}
|
|
|
== other items (definition lists, comments) ==
|
item | tbwiki | reStructuredText
_________________|____________________|____________________
| |
definition | ; term: definition | term
| | definition description
| |
| | use same indent to continue
_________________|____________________|____________________
| |
| |
comment | {{{# comment here | .. comment here
| }}} |
| |
| |
|
{{{
item | tbwiki | reStructuredText
_________________|____________________|____________________
| |
definition | ; term: definition | term
| | definition description
| |
| | use same indent to continue
_________________|____________________|____________________
| |
| |
comment | {{{# comment here | .. comment here
| }}} |
| |
| |
|
|
}}}
|
}}}
|
|
|
== blocks and quoted ==
|
|
{{{
|
|
item | tbwiki | reStructuredText
_____________|________________________________|____________________
| |
block | {{{ | previous paragraph
| indented | indented
| content | content
| }}} | previous indentation level
_____________|________________________________|____________________
| |
| | .. note:: content in
colored | {{{#!YellowBox | note block
block | content | .. tip:: content in
| }}} | note block (also warning:, error: important: caution:)
| |
| | last part of preceding paragraph ::
| |
| | stuff in block
_____________|________________________________|____________________
| |
labeled | |
offset block | (not available) | .. note:: content in note block
_____________|________________________________|____________________
| |
}}}
|
item | tbwiki | reStructuredText
_____________|________________________________|____________________
| |
block | {{{ | previous paragraph
| indented | indented
| content | content
| }}} | previous indentation level
_____________|________________________________|____________________
| |
| | .. note:: content in
colored | {{{#!YellowBox | note block
block | content | .. tip:: content in
| }}} | note block (also warning:, error: important: caution:)
| |
| | last part of preceding paragraph ::
| |
| | stuff in block
_____________|________________________________|____________________
| |
labeled | |
offset block | (not available) | .. note:: content in note block
_____________|________________________________|____________________
| |
}}}
|
|
|
== links ==
note labels and anchors are case-insensitive in rst.
|
|
By convention, explicit declarations of labels are lower case.
|
By convention, explicit declarations of labels are lower case.
|
http://example.com/Example
item | tbwiki | reStructuredText
_____________|________________________________|____________________
| |
URL | | http://example.com/
_____________|________________________________|____________________
| |
URL with | | `Example http://example.com/`_
cover text | |
_____________|________________________________|____________________
| |
internal | [[#Section Name]] | `section_name`_
_____________|________________________________|____________________
| |
page | [[Page Name]] | :doc:`Page Name`
| | (depends on whether first
| | section heading matches
| | page name)
| |
| | :ref:`Page Name <page_nm>`
| | (when a separate anchor has
| | been created for a page,)
| |
_____________|________________________________|____________________
| |
page with | [[Page Name|Cover text]] | :doc:`Cover Text <page name>`
cover text | |
_____________|________________________________|____________________
| |
define |{{HTML(<a name="new_lbl"></a>)}}| .. _new_label:
anchor | |
_____________|________________________________|____________________
| |
define | (not available) | `Example`_
URL separate | | ...
from cover | |
text | | .. _Example: http://example.com/
| |
_____________|________________________________|____________________
| |
}}}
|
{{{
item | tbwiki | reStructuredText
_____________|________________________________|____________________
| |
URL | http://example.com/ | http://example.com/
_____________|________________________________|____________________
| |
URL with | [[http://example.com|Example]] | `Example http://example.com/`_
cover text | |
_____________|________________________________|____________________
| |
internal | [[#Section Name]] | `section_name`_
_____________|________________________________|____________________
| |
page | [[Page Name]] | :doc:`Page Name`
| | (depends on whether first
| | section heading matches
| | page name)
| |
| | :ref:`Page Name <page_nm>`
| | (when a separate anchor has
| | been created for a page,)
| |
_____________|________________________________|____________________
| |
page with | [[Page Name|Cover text]] | :doc:`Cover Text <page name>`
cover text | |
_____________|________________________________|____________________
| |
define |{{HTML(<a name="new_lbl"></a>)}}| .. _new_label:
anchor | |
_____________|________________________________|____________________
| |
define | (not available) | `Example`_
URL separate | | ...
from cover | |
text | | .. _Example: http://example.com/
| |
_____________|________________________________|____________________
| |
}}}
|
|
See https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref for recommendations
on using :ref: It's still a bit unclear to me how to force it to a specific
cover text. It appears that it uses a section name following the anchor
definition as the cover text, unless overridden. The purpose of this
appears to be to let the :ref: handle section renames, without the user
having to go to all references and fix them up.
|
See https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref for recommendations
on using :ref: It's still a bit unclear to me how to force it to a specific
cover text. It appears that it uses a section name following the anchor
definition as the cover text, unless overridden. The purpose of this
appears to be to let the :ref: handle section renames, without the user
having to go to all references and fix them up.
|
|
|
= Macros and directives =
|
item | tbwiki | reStructuredText
_____________|________________________________|____________________
| |
include | {{Include(page-or-ref)}} | .. include: included-file.txt
_____________|________________________________|____________________
| |
}}}
|
{{{
item | tbwiki | reStructuredText
_____________|________________________________|____________________
| |
include | {{Include(page-or-ref)}} | .. include: included-file.txt
_____________|________________________________|____________________
| |
}}}
|