topic¶
topic is a block with a title and content. Use topic to wrap ideas not strictly related the text, but useful for readers. For example, in the documentation covering authentication, it might be useful to mention that users should choose strong password.
Requires title and content¶
You need to pass a title after topic:: (note the space after ::), and a content bellow the blank line.
1Nisi occaecat sit reprehenderit incididunt fugiat in sunt. Velit irure et amet aliquip sunt.
2
3.. topic:: Topic title
4
5 Pariatur nulla officia culpa qui commodo cupidatat ea elit aliqua cillum amet elit.
6
7Dolor adipisicing irure et sit ullamco veniam aliqua. Non laboris duis veniam quis occaecat.
Nisi occaecat sit reprehenderit incididunt fugiat in sunt. Velit irure et amet aliquip sunt.
Dolor adipisicing irure et sit ullamco veniam aliqua. Non laboris duis veniam quis occaecat.
Cannot occur inside body elements or other topic¶
topic may only occur anywhere a section or transition may occur. Nesting topic inside body element or topic, e.g.:
.. topic:: Topic
Topic cannot be nested inside body elements or another topic.
.. topic:: Another topic
Another topic content.
causes the following error WARNING: The "topic" directive may not be used within topics or body elements.
Directive name in uppercase¶
Directive name is case insensitive (like all directive and role names). Most documentation and book authors prefer typing directives and roles all in lowercase. However, writing directive name in uppercase corresponds with their “raise attention” objective and improves reStructuredText code readability.
1.. TOPIC::
2
3 Writing topic uppercase can be considered as reasonable exception to "all-lowercase" rule.
Complex content¶
Any reStructuredText elements can be in topic content. As always, you need only to keep correct indentation.
1.. topic:: Complex content
2
3 This is the topic with complex body containing
4
5 - two items
6 - bullet list
7
8 And, code example::
9
10 $ nano ~/.bash_aliases
Previous: toctree | Next: transition