Skip to content

rST documentation fixes, part 1: preparation #2011

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 21, 2025
Merged

rST documentation fixes, part 1: preparation #2011

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
882168c
Update rST parser documentation: preparation
gmilde Jun 2, 2025
7a3af3e
Synchronize rST parser documentation files.
gmilde Jun 2, 2025
5195478
rST documentation fixup.
gmilde Oct 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 78 additions & 54 deletions docs/user/rest.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,9 @@ reST (reStructuredText) Markup
===============================

..
This document is duplicated within Moin2 as `/docs/user/rest.rst` and
`contrib/sample/rst.data`. Please update both.
This document is duplicated within the Moin2 repository as
`docs/user/rest.rst` and `src/moin/help/help-en/rst.data`.
Please update both.

Depending on your source, this document may have been created by
the Moin2 reST parser (Docutils) or the Sphinx reST parser. These parsers
Expand Down Expand Up @@ -92,60 +93,82 @@ Text formatting

The following is a table of inline markup that can be used to format text in Moin.

+----------------------------------------+------------------------------------+
|Markup |Result |
+========================================+====================================+
|``**Bold Text**`` |**Bold text** |
+----------------------------------------+------------------------------------+
|``*Italic*`` |*Italic* |
+----------------------------------------+------------------------------------+
|````Inline Literals```` |``Inline Literals`` |
+----------------------------------------+------------------------------------+
|``***nested markup is not supported***``|***nested markup is not supported***|
+----------------------------------------+------------------------------------+
======================================== ====================================
Markup Result
======================================== ====================================
``**Bold Text**`` **Bold text**

``*Italic*`` *Italic*

````Inline Literals```` ``Inline Literals``

``***nested markup is not supported***`` ***nested markup is not supported***
======================================== ====================================


Hyperlinks
==========

External Links
--------------

+-----------------------------------------------------------------+-------------------------------------------------------------+
|Markup |Result |
+=================================================================+=============================================================+
|``https://www.python.org/`` |https://www.python.org/ |
+-----------------------------------------------------------------+-------------------------------------------------------------+
|``External hyperlinks, like `Python <https://www.python.org/>`_``|External hyperlinks, like `Python <https://www.python.org/>`_|
+----------------------------------------------------------------+--------------------------------------------------------------+
|``External hyperlinks, like Moin_.`` |External hyperlinks, like Moin_. |
| | |
|``.. _Moin: http://moinmo.in/`` |.. _Moin: http://moinmo.in/ |
+-----------------------------------------------------------------+-------------------------------------------------------------+
================================================================ =====================================================
Markup Result
================================================================ =====================================================
``http://www.python.org/`` http://www.python.org/

``External hyperlinks, like `Python <http://www.python.org/>`_`` External hyperlinks, like
`Python <http://www.python.org/>`_

``External hyperlinks, like Moin_.`` External hyperlinks, like Moin_.

``.. _Moin: http://moinmo.in/`` .. _Moin: http://moinmo.in/
================================================================ =====================================================

Internal Links
--------------

The examples below use the "help-en" and "help-common" namespaces
to separate these help pages from the main wiki content.
Some target pages may be missing from the default namespace.

Within the rst syntax:

* a link like ``http:Home`` links to an item in the default namespace
* a link like ``http:/subitem`` links to a subitem of the current item
* a link that begins with a namespace like ``http:users/Home`` links to the Home item in the target namespace
* a link like ``http:../sibling`` links to a sibling of the current item

.. _myanchor:

+----------------------------------------------------------------+------------------------------------------------------------+
|Markup |Result |
+================================================================+============================================================+
|``http:Home`` link to a page in this wiki |http:Home link to a page in this wiki |
+----------------------------------------------------------------+------------------------------------------------------------+
|```Home <http:Home>`_`` link to a page in this wiki |`Home <http:Home>`_ link to a page in this wiki |
+----------------------------------------------------------------+------------------------------------------------------------+
|``Headings_`` link to heading anchor on this page |Headings_ link to heading anchor on this page |
+----------------------------------------------------------------+------------------------------------------------------------+
|```Internal Links`_`` link to heading with embedded blanks |`Internal Links`_ link to heading with embedded blanks |
+----------------------------------------------------------------+------------------------------------------------------------+
|``.. _myanchor:`` create anchor, real anchor is above this table|create anchor, real anchor is above this table |
+----------------------------------------------------------------+------------------------------------------------------------+
|``myanchor_`` link to above anchor |myanchor_ link to above anchor |
+----------------------------------------------------------------+------------------------------------------------------------+
============================ ============================ ===========================================================
Markup Result Comment
============================ ============================ ===========================================================
``http:Home`` http:Home link to an item in the default namespace of this wiki

```Home2 <http:Home>`_`` `Home2 <http:Home>`_ fancy link to an item in the default namespace of this wiki

``http:/subitem`` http:/subitem link to a subitem of the current item

```sub <http:/subitem>`_`` `sub <http:/subitem>`_ fancy link to a subitem of the current item

``http:users/Home`` http:users/Home link to an item in a different namespace of this wiki

``http:../moin`` http:../moin link to a sibling of this item

``Headings_`` Headings_ link to Headings anchor on this item

```Internal Links`_`` `Internal Links`_ link to a heading with embedded blanks

``.. _myanchor:`` create anchor, real anchor is above this table

``myanchor_`` myanchor_ link to above anchor
============================ ============================ ===========================================================

**Notes:**
- If this page was created by Sphinx, none of the above internal link examples work correctly.
- The ".. _myanchor:" directive must begin in column one.
- The block level "target" ``.. _myanchor:`` sets an anchor for the following element.
Inline targets set the anchor on the text content which is also used as label.
- Section titles (or headings) automatically generate hyperlink targets (the title
text is used as the hyperlink name).

Expand All @@ -161,11 +184,11 @@ several images declared successively without any positioning will display in a h

Before text.

.. image:: png
:height: 100
.. image:: help-common/logo.svg
:height: 200
:width: 200
:scale: 50
:alt: alternate text png
:scale: 100
:alt: alternate text logo.svg
:align: center

After text.
Expand All @@ -174,18 +197,18 @@ several images declared successively without any positioning will display in a h

Before text.

.. image:: png
:height: 100
.. image:: help-common/logo.svg
:height: 200
:width: 200
:scale: 50
:alt: alternate text png
:scale: 100
:alt: alternate text logo.svg
:align: center

After text.

**Notes:**
- The Sphinx parser does not have an image named "png" so the alternate text
will be displayed.
- The Sphinx parser does not have an image named "logo.svg" so the alternate text
will be displayed above.

Figures
=======
Expand All @@ -198,11 +221,11 @@ will display in a column.

Before text.

.. figure:: png
.. figure:: help-common/logo.png
:height: 100
:width: 200
:scale: 50
:alt: alternate text png
:alt: alternate text logo.png

Moin Logo

Expand All @@ -213,13 +236,14 @@ will display in a column.

**Result**:


Before text.

.. figure:: png
.. figure:: help-common/logo.png
:height: 100
:width: 200
:scale: 50
:alt: alternate text png
:alt: alternate text logo.png

Moin Logo

Expand Down
Loading