.. _restructured_text_cheat_sheet:
============================
ReStructuredText Cheat Sheet
============================
The following tips should help you get started writing reStructuredText
.. _learn_plugin_development_add_docs_sections:
Sections
````````
Sections are created by underlining (and optionally overlining) the section title with a
punctuation character, at least as long as the text and a blank line before and after.
These section titles and headings will be used to create the contents when the
documentation is built.
.. note:: The Page Title can be seen at the top of this page,
:ref:`learn_plugin_development_add_docs`.
Header 1 can be seen at the top of this section,
:ref:`learn_plugin_development_add_docs_sections`.
Header 2
````````
Sample paragraph.
Header 3
~~~~~~~~
Sample paragraph.
----
If you expand the page contents you will notice that "Header 3" isn't available in the
page contents. This is because the maxdepth of the toctree is '2'.
see :ref:`learn_plugin_development_add_docs_toctree`
This is an example of the "Add Documentation"(Page Title), "Sections"(Header 1), "Header
2", and "Header 3" raw text:
::
=================
Add Documentation
=================
Sections
--------
Header 2
````````
Header 3
~~~~~~~~
Instruction Divider
-------------------
Four dashes with a leading blank line and following blank line.
----
::
----
Text Formatting
---------------
The following roles don’t do anything special except formatting the text in a different
style.
Inline Markups
``````````````
Inline markup is quite simple, some examples:
- one asterisk: :code:`*text*`, *text* for emphasis (italics),
- two asterisks: :code:`**text**`, **text** for strong emphasis (boldface), and
- backquotes: :code:`:code:`text``, :code:`text` for code samples.
Files
`````
The name of a file or directory. Within the contents, you can use curly braces to
indicate a “variable” part, for example:
:file:`learn_plugin_development/LearnPluginDevelopment_AddDocs.rst`
::
:file:`learn_plugin_development/LearnPluginDevelopment_AddDocs.rst`
Reference Links
```````````````
Reference link names must be unique throughout the entire documentation.
Place a label directly before a section title.
The link name will match the section title.
:ref:`learn_plugin_development_add_docs`
An example of the reference link above the section title:
::
.. _learn_plugin_development_add_docs:
=================
Add Documentation
=================
An example of the reference link:
::
:ref:`learn_plugin_development_add_docs`
URL Link
````````
A raw link can be entered without a title, but if a title is entered be sure to leave a
space before the URL address:
`Synerty `_
::
`Synerty `_
Code Block
``````````
Two semi-colons followed by a blank line and two leading tabs for each line of code.
The code block is ended by contents written without leading tabs.
::
this.code
::
::
this.code
Bullets
```````
- First point
- Second point
::
- First point
- Second point
Numbered Lists
``````````````
#. First point
#. Second point
::
#. First point
#. Second point
Directives
``````````
Directives are indicated by an explicit markup start '.. ' followed by the directive
type, two colons, and whitespace (together called the "directive marker"). Directive
types are case-insensitive single words.
Images
``````
The filename given must either be relative to the source file, or absolute which means
that they are relative to the top source directory.
.. image:: peek_plugin_tutorial/synerty_logo_400x800.png
::
.. image:: peek_plugin_tutorial/synerty_logo_400x800.png
Admonitions
```````````
Admonitions are specially marked "topics" that can appear anywhere an ordinary body
element can. They contain arbitrary body elements. Typically, an admonition is rendered
as an offset block in a document, sometimes outlined or shaded, with a title matching
the admonition type.
.. note:: Multi
Line
NOTE
Mutli Parapgraph
- Can contain bullets
#. numbers points
and references: :ref:`learn_plugin_development_add_docs`
::
.. note:: Multi
Line
NOTE
Mutli Parapgraph
- Can contain bullets
#. numbers points
and references: :ref:`learn_plugin_development_add_docs`
.. _learn_plugin_development_add_docs_toctree:
TOC tree
````````
This directive inserts a table of contents at the current location, including sub-TOC
trees.
Document titles in the toctree will be automatically read from the title of the
referenced document.
----
Here is an example:
::
=====================
Example Documentation
=====================
.. toctree::
:maxdepth: 2
:caption: Contents:
intro
strings
datatypes
numeric
(many more documents listed here)
.. _learn_plugin_development_add_docs_docstring_format:
Docstring Format
````````````````
This extension :file:`sphinx.ext.autodoc`, can import the modules you are documenting,
and pull in documentation from docstrings in a semi-automatic way.
.. warning:: autodoc imports the modules to be documented. If any modules have side
effects on import, these will be executed by autodoc when sphinx-build is run. If
you document scripts (as opposed to library modules), make sure their main routine
is protected by a if __name__ == '__main__' condition.
A docstring is a string literal that occurs as the first statement in a module,
function, class, or method definition.
All modules should normally have docstrings, and all functions and classes exported by
a module should also have docstrings. Public methods (including the __init__
constructor) should also have docstrings. A package may be documented in the module
docstring of the __init__.py file in the package directory.
Example:
::
"""
This is a reST style.
:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""
Below is an abstract from file
:file:`peek_plugin_tutorial/_private/server/LogicEntryHook.py`, create in the step
:ref:`learn_plugin_development_add_logic_add_file_LogicEntryHook`.
::
def load(self) -> None:
""" Start
This will be called to start the plugin.
Start, means what ever we choose to do here. This includes:
- Create Controllers
- Create payload, observable and tuple action handlers.
"""
logger.debug("Loaded")
Below is an abstract from file
:file:`peek-plugin-base/peek_plugin_base/PeekPlatformCommonHookABC.py`
::
class PeekPlatformCommonHookABC(metaclass=ABCMeta):
@abstractmethod
def getOtherPluginApi(self, pluginName:str) -> Optional[object]:
""" Get Other Plugin Api
Asks the plugin for its api object and return it to this plugin.
The API returned matches the platform service.
:param pluginName: The name of the plugin to retrieve the API for
:return: An instance of the other plugins API for this Peek Platform
Service.
"""