Skip to content

Commit e51fb1f

Browse files
pekkaklarckpekkaklarck
committed
Documentation: Overall Markdown syntax documentation
This is part of Libdoc's Markdown support (robotframework#5304). Still need to document how to actually use Markdown with Libdoc and what extra features (mostly automatic link targets) it provides. Also some changes elsewhere in the User Guide, mostly to avoid conflicting section headers.
1 parent 7909206 commit e51fb1f

9 files changed

Lines changed: 632 additions & 145 deletions

File tree

‎doc/userguide/src/Appendices/DocumentationFormatting.rst‎

Lines changed: 565 additions & 77 deletions
Large diffs are not rendered by default.

‎doc/userguide/src/Appendices/Registrations.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,16 +10,16 @@ Suite file extensions
1010
`Suite files`_ with the following extensions are parsed automatically:
1111

1212
:file:`.robot`
13-
Suite file using the `plain text format`_.
13+
Suite file using the `plain text data format`_.
1414

1515
:file:`.robot.rst`
16-
Suite file using the `reStructuredText format`_.
16+
Suite file using the `reStructuredText data format`_.
1717

1818
:file:`.robot.md`
19-
Suite file using the `Markdown format`_.
19+
Suite file using the `Markdown data format`_.
2020

2121
:file:`.rbt`
22-
Suite file using the `JSON format`_.
22+
Suite file using the `JSON data format`_.
2323

2424
Using other extensions is possible, but it requires `separate configuration`__.
2525

@@ -46,7 +46,7 @@ Resource file extensions
4646
:file:`.rsrc` and :file:`.json`
4747
Resource file using the `JSON format`__.
4848

49-
__ `Resource files using reStructured text format`_
49+
__ `Resource files using reStructuredText format`_
5050
__ `Resource files using Markdown format`_
5151
__ `Resource files using JSON format`_
5252

‎doc/userguide/src/CreatingTestData/CreatingTestCases.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -477,8 +477,8 @@ use special `continuable failures`__ if stopping test execution is not desired.
477477

478478
__ `Continue on failure`_
479479

480-
Error messages
481-
~~~~~~~~~~~~~~
480+
Error message
481+
~~~~~~~~~~~~~
482482

483483
The error message assigned to a failed test case is got directly from the
484484
failed keyword. Often the error message is created by the keyword itself, but

‎doc/userguide/src/CreatingTestData/ResourceAndVariableFiles.rst‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,10 @@ Resource files
2222
--------------
2323

2424
Resource files are typically created using the plain text format, but also
25-
`reStructuredText format`__ and `JSON format`__ are supported.
25+
reStructuredText__, Markdown__ and JSON__ resource files are supported.
2626

27-
__ `Resource files using reStructured text format`_
27+
__ `Resource files using reStructuredText format`_
28+
__ `Resource files using Markdown format`_
2829
__ `Resource files using JSON format`_
2930

3031
Taking resource files into use
@@ -134,10 +135,10 @@ Example resource file
134135
[Arguments] ${password}
135136
Input Text password_field ${password}
136137

137-
Resource files using reStructured text format
138-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
138+
Resource files using reStructuredText format
139+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
139140

140-
The `reStructuredText format`_ that can be used with `suite files`_ works
141+
The `reStructuredText data format`_ that can be used with `suite files`_ works
141142
also with resource files. Such resource files can use either :file:`.rst`
142143
or :file:`.rest` extension and they are otherwise imported exactly as
143144
normal resource files:
@@ -179,12 +180,12 @@ defines `${MESSAGE}` variable and creates :name:`My Keyword` keyword:
179180
| My Keyword | [Arguments] | ${path} |
180181
| | Directory Should Exist | ${path} |
181182
182-
__ `reStructuredText format`_
183+
__ `reStructuredText data format`_
183184

184185
Resource files using Markdown format
185-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
186+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
186187

187-
The `Markdown format`_ that can be used with `suite files`_ works also with
188+
The `Markdown data format`_ that can be used with `suite files`_ works also with
188189
resource files. Such resource files can use either :file:`.md` or
189190
:file:`.markdown` extension and they are otherwise imported exactly as normal
190191
resource files:
@@ -225,7 +226,7 @@ defines ``${MESSAGE}`` variable and creates :name:`My Keyword` keyword:
225226
| | Directory Should Exist | ${path} |
226227
```
227228

228-
__ `Markdown format`_
229+
__ `Markdown data format`_
229230

230231
Resource files using JSON format
231232
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -257,7 +258,7 @@ recreated using `ResourceFile.from_json`__:
257258
# Recreate resource from JSON data.
258259
resource = ResourceFile.from_json('example.rsrc')
259260

260-
__ `JSON format`_
261+
__ `JSON data format`_
261262
__ https://robot-framework.readthedocs.io/en/master/autodoc/robot.running.html#robot.running.model.ResourceFile.to_json
262263
__ https://robot-framework.readthedocs.io/en/master/autodoc/robot.running.html#robot.running.model.ResourceFile.from_json
263264

‎doc/userguide/src/CreatingTestData/TestDataSyntax.rst‎

Lines changed: 20 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -101,10 +101,10 @@ Supported file formats
101101
----------------------
102102

103103
The most common approach to create Robot Framework data is using the
104-
`space separated format`_ where pieces of the data, such as keywords
104+
`space separated data format`_ where pieces of the data, such as keywords
105105
and their arguments, are separated from each others with two or more spaces.
106-
An alternative is using the `pipe separated format`_ where the separator is
107-
the pipe character surrounded with spaces (:codesc:`\ |\ `).
106+
An alternative is using the `pipe separated data format`_ where the separator
107+
is the pipe character surrounded with spaces (:codesc:`\ |\ `).
108108

109109
Suite files typically use the :file:`.robot` extension, but what files are
110110
parsed `can be configured`__. `Resource files`_ can use the :file:`.robot`
@@ -123,7 +123,7 @@ data is `embedded into code blocks`__. Only files with the :file:`.robot.md`
123123
extension are parsed by default. If you would rather use just :file:`.md` or
124124
:file:`.markdown` extension, that needs to be configured separately.
125125

126-
Robot Framework data can also be created in the `JSON format`_ that is targeted
126+
Robot Framework supports also `JSON data format`_ that is targeted
127127
more for tool developers than normal Robot Framework users. Only JSON files
128128
with the custom :file:`.rbt` extension are parsed by default.
129129

@@ -137,14 +137,15 @@ with Robot Framework 3.1 because newer versions do not understand the HTML
137137
format at all.
138138

139139
__ `Selecting files to parse`_
140-
__ `reStructuredText format`_
141-
__ `Markdown format`_
140+
__ `reStructuredText data format`_
141+
__ `Markdown data format`_
142142

143+
.. _space separated format:
143144
.. _space separated plain text format:
144-
.. _plain text format:
145+
.. _plain text data format:
145146

146-
Space separated format
147-
~~~~~~~~~~~~~~~~~~~~~~
147+
Space separated data format
148+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
148149

149150
When Robot Framework parses data, it first splits the data to lines and then
150151
lines to tokens such as keywords and arguments. When using the space
@@ -191,8 +192,10 @@ in the actual data. It is possible to use special escape syntax like
191192
were converted to ASCII spaces during parsing. Nowadays all data
192193
is preserved as-is.
193194

194-
Pipe separated format
195-
~~~~~~~~~~~~~~~~~~~~~
195+
.. _pipe separated format:
196+
197+
Pipe separated data format
198+
~~~~~~~~~~~~~~~~~~~~~~~~~~
196199

197200
The biggest problem of the space delimited format is that visually
198201
separating keywords from arguments can be tricky. This is a problem
@@ -243,8 +246,8 @@ __ Escaping_
243246
in Robot Framework 3.2. Prior to it non-ASCII spaces used in
244247
the data were also converted to ASCII spaces.
245248

246-
reStructuredText format
247-
~~~~~~~~~~~~~~~~~~~~~~~
249+
reStructuredText data format
250+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
248251

249252
reStructuredText_ (reST) is an easy-to-read plain text markup syntax that
250253
is commonly used for documentation of Python projects, including Python itself
@@ -321,8 +324,8 @@ when processing files using reStructuredText tooling normally.
321324
.. note:: Parsing :file:`.robot.rst` files automatically is new in
322325
Robot Framework 6.1.
323326

324-
Markdown format
325-
~~~~~~~~~~~~~~~
327+
Markdown data format
328+
~~~~~~~~~~~~~~~~~~~~
326329

327330
Markdown_ is a lightweight plain text markup syntax that is widely used for
328331
documentation, README files, and technical content across the software
@@ -388,8 +391,8 @@ __ `Selecting files to parse`_
388391

389392
.. note:: Markdown support is new in Robot Framework 7.5.
390393

391-
JSON format
392-
~~~~~~~~~~~
394+
JSON data format
395+
~~~~~~~~~~~~~~~~
393396

394397
Robot Framework supports data also in the JSON_ format. This format is designed
395398
more for tool developers than for regular Robot Framework users and it is not

‎doc/userguide/src/ExecutingTestCases/ConfiguringExecution.rst‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -36,9 +36,9 @@ Examples::
3636
robot x.robot y.rst # Parse both files using an appropriate parser.
3737

3838
__ `Supported file formats`_
39-
__ `reStructuredText format`_
40-
__ `Markdown format`_
41-
__ `JSON format`_
39+
__ `reStructuredText data format`_
40+
__ `Markdown data format`_
41+
__ `JSON data format`_
4242
__ `Using custom parsers`_
4343

4444
Included and excluded files
@@ -60,9 +60,9 @@ the following rules:
6060

6161
__ `Suite directories`_
6262
__ `Supported file formats`_
63-
__ `reStructuredText format`_
64-
__ `Markdown format`_
65-
__ `JSON format`_
63+
__ `reStructuredText data format`_
64+
__ `Markdown data format`_
65+
__ `JSON data format`_
6666
__ `Using custom parsers`_
6767

6868
Selecting files by name or path
@@ -114,9 +114,9 @@ it is the file name, not the original pattern. In such cases you need
114114
to quote or escape the pattern like `'*.robot'` or `\*.robot`.
115115

116116
__ `Included and excluded files`_
117-
__ `reStructuredText format`_
118-
__ `Markdown format`_
119-
__ `JSON format`_
117+
__ `reStructuredText data format`_
118+
__ `Markdown data format`_
119+
__ `JSON data format`_
120120
__ `Supported file formats`_
121121

122122
.. note:: :option:`--parseinclude` is new in Robot Framework 6.1.

‎doc/userguide/src/ExtendingRobotFramework/CreatingTestLibraries.rst‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2440,8 +2440,6 @@ exception type as a prefix to failure message also with non generic exceptions.
24402440
This is done by adding a special `ROBOT_SUPPRESS_NAME` attribute with
24412441
value `True` to your exception.
24422442

2443-
Python:
2444-
24452443
.. sourcecode:: python
24462444

24472445
class MyError(RuntimeError):

‎doc/userguide/src/RobotFrameworkUserGuide.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -245,3 +245,4 @@
245245
.. _Slack: http://slack.robotframework.org
246246
.. _Markdown: https://en.wikipedia.org/wiki/Markdown
247247
.. _CommonMark: https://spec.commonmark.org
248+
.. _Python-Markdown: https://python-markdown.github.io

‎doc/userguide/src/SupportingTools/Libdoc.rst‎

Lines changed: 19 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -447,7 +447,7 @@ line.
447447

448448
"""Example library in Robot Framework format.
449449

450-
- Formatting with *bold* and _italic_.
450+
- Formatting with *bold* and _italics_.
451451
- URLs like http://example.com are turned to links.
452452
- Custom links like [http://robotframework.org|Robot Framework] are supported.
453453
- Linking to `My Keyword` works.
@@ -456,17 +456,16 @@ line.
456456
def my_keyword():
457457
"""Nothing more to see here."""
458458

459-
Creating table of contents automatically
460-
''''''''''''''''''''''''''''''''''''''''
459+
Creating table of contents
460+
''''''''''''''''''''''''''
461461

462462
With bigger libraries it is often useful to add a table of contents to
463463
the library introduction. When using the Robot Framework documentation format,
464464
this can be done automatically by adding a special `%TOC%` marker into a line
465465
on its own. The table of contents is created based on the top-level
466-
`section titles`_ (e.g. `= Section =`) used in the introduction. In addition
466+
`section headers`_ (e.g. `= Section =`) used in the introduction. In addition
467467
to them, the TOC also gets links to the `automatically created sections`__
468-
for shortcuts and keywords as well as for importing and tags sections when
469-
applicable.
468+
for keywords and importing.
470469

471470
.. sourcecode:: python
472471

@@ -479,22 +478,20 @@ applicable.
479478

480479
%TOC%
481480

482-
= Section title =
481+
= Section header =
483482

484-
The top-level section titles are automatically added to the TOC.
483+
The top-level section headers are automatically added to the TOC.
485484

486485
= Second section =
487486

488487
== Sub section ==
489488

490-
Sub section titles are not added to the TOC.
489+
Sub section headers are not added to the TOC.
491490
"""
492491

493492
def my_keyword():
494493
"""Nothing more to see here."""
495494

496-
.. note:: Automatic TOC generation is a new feature in Robot Framework 3.2.
497-
498495
__ `Linking to automatic sections`_
499496

500497
HTML documentation syntax
@@ -513,7 +510,7 @@ on the command line like `--docformat HTML`.
513510

514511
.. sourcecode:: python
515512

516-
"""Example library in HTML format.
513+
"""Example library using HTML format.
517514

518515
<ul>
519516
<li>Formatting with <b>bold</b> and <i>italic</i>.
@@ -538,7 +535,7 @@ like :codesc:`\`My Keyword\``.
538535

539536
.. sourcecode:: python
540537

541-
"""Example library in plain text format.
538+
"""Example library using plain text format.
542539

543540
- Formatting is not supported.
544541
- URLs like http://example.com are turned to links.
@@ -567,12 +564,12 @@ languages that Pygments supports.
567564

568565
.. sourcecode:: python
569566

570-
"""Example library in reStructuredText format.
567+
"""Example library using reStructuredText format.
571568

572-
- Formatting with **bold** and *italic*.
569+
- Formatting with **bold** and *italics*.
573570
- URLs like http://example.com are turned to links.
574571
- Custom links like reStructuredText__ are supported.
575-
- Linking to \`My Keyword\` works but requires backtics to be escaped.
572+
- Linking to \`My Keyword\` works but requires backticks to be escaped.
576573

577574
__ http://docutils.sourceforge.net
578575

@@ -602,7 +599,7 @@ There is no error or warning if a link target is not found, but instead Libdoc
602599
just formats the text in italics. Earlier this formatting was recommended to
603600
be used when referring to keyword arguments, but that was problematic because
604601
it could accidentally create internal links. Nowadays it is recommended to
605-
use `inline code style <inline styles_>`__ with double backticks like
602+
use `inline code style <Robot inline styles_>`__ with double backticks like
606603
:codesc:`\`\`argument\`\`` instead. The old formatting of single backticks
607604
may even be removed in the future in favor of giving an error when a link
608605
target is not found.
@@ -674,11 +671,10 @@ __ `Keyword tags`_
674671
Linking to custom sections
675672
~~~~~~~~~~~~~~~~~~~~~~~~~~
676673

677-
Robot Framework's `documentation syntax`_
678-
supports custom `section titles`_, and the titles used in the
679-
library or resource file introduction automatically create link
680-
targets. The example below illustrates linking both to automatic and
681-
custom sections:
674+
Robot Framework's `documentation syntax`_ supports custom `section headers`_,
675+
and the headers used in the library or resource file introduction automatically
676+
create link targets. The example below illustrates linking both to automatic
677+
and custom sections:
682678

683679
.. sourcecode:: python
684680

@@ -729,7 +725,7 @@ __ kwargs-library_
729725
__ `Keyword arguments`_
730726

731727
When referring to arguments in keyword documentation, it is recommended to
732-
use `inline code style <inline styles_>`__ like :codesc:`\`\`argument\`\``.
728+
use `inline code style <Robot inline styles_>`__ like :codesc:`\`\`argument\`\``.
733729

734730
Automatically listing type documentation
735731
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)