diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..a89a1e3f1 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +recommonmark +Sphinx +sphinx-bootstrap-theme diff --git a/docs/source/Controller/Controller.rst b/docs/source/Controller/Controller.rst index 81c1db4aa..6fd399690 100644 --- a/docs/source/Controller/Controller.rst +++ b/docs/source/Controller/Controller.rst @@ -2,9 +2,11 @@ Controller ********** A controller is a component to enable a plugin to send data elsewhere. -Up-to 3 controllers can be active in ESPEasy. -Per plugin up-to 3 active controllers can be selected and for some controllers -an additional parameter can be given. + +- Up-to 3 controllers can be active in ESPEasy. +- Per plugin up-to 3 active controllers can be selected. +- For some controllers an additional parameter can be given. + For example, Domoticz needs an 'IDX' value to identify the configured entry in Domoticz for which new data is sent. @@ -23,22 +25,23 @@ Generic fields Send queue parameters --------------------- +Controllers have a queue to keep unsent messages. +This queue is used to handle message bursts and also store messages which are recorded +before WiFi connection is made or during lost connection. + - **Minimum Send Interval** - Minimum time between two messages in msec. - **Max Queue Depth** - Maximum length of the buffer queue to keep unsent messages. - **Max Retries** - Maximum number of retries to send a message. - **Full Queue Action** - How to handle when queue is full, ignore new or delete oldest message. - **Client Timeout** - Timeout in msec for an network connection used by the controller. -Controllers have a queue to keep unsent messages. -This queue is used to handle message bursts and also store messages which are recorded -before WiFi connection is made or during lost connection. - -Some controllers, like ThingSpeak, need a specific configuration. -ThingSpeak only allows a message every 15 seconds for the free accounts. Sample ThingSpeak configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Some controllers, like ThingSpeak, need a specific configuration. +ThingSpeak only allows a message every 15 seconds for the free accounts. + - **Minimum Send Interval** - 15000 msec - **Max Queue Depth** - 1 (only report the last value) - **Max Retries** - 2 diff --git a/docs/source/ESPEasy/AboutUs.rst b/docs/source/ESPEasy/AboutUs.rst new file mode 100644 index 000000000..7bc32d75f --- /dev/null +++ b/docs/source/ESPEasy/AboutUs.rst @@ -0,0 +1,2 @@ +About Us +******** diff --git a/docs/source/ESPEasy/espeasy_logo.png b/docs/source/ESPEasy/espeasy_logo.png new file mode 100644 index 000000000..3fc1cb4c2 Binary files /dev/null and b/docs/source/ESPEasy/espeasy_logo.png differ diff --git a/docs/source/Participate/Documentation.rst b/docs/source/Participate/Documentation.rst new file mode 100644 index 000000000..5ec294a3f --- /dev/null +++ b/docs/source/Participate/Documentation.rst @@ -0,0 +1,35 @@ +Documentation +************* + +For documentation we use Sphinx and this will be read by ReadTheDocs. +We use the `Sphinx Bootstrap Theme `_ + +This documentation is included in the GitHub repository. +It allows us to create documentation per version of ESPEasy. + +See also the `ESPEasy wiki `_ +for more documentation which has not been moved here. + +Needed Python packages:: + + pip install sphinx recommonmark sphinx_bootstrap_theme + +PlatformIO with Atom +==================== + +With the ESPEasy project open in Atom, open the PIO terminal in Atom. + +Install dependencies:: + + cd docs + pip install ... (see needed Python packages above) + +Build on Windows:: + + cd docs + .\make.bat html + +Build on Linux/Mac:: + + cd docs + ./make html diff --git a/docs/source/Plugin/Plugin.rst b/docs/source/Plugin/Plugin.rst new file mode 100644 index 000000000..262e9d649 --- /dev/null +++ b/docs/source/Plugin/Plugin.rst @@ -0,0 +1,2 @@ +Plugins +******* diff --git a/docs/source/Reference/Command.rst b/docs/source/Reference/Command.rst new file mode 100644 index 000000000..bc82b10f3 --- /dev/null +++ b/docs/source/Reference/Command.rst @@ -0,0 +1,2 @@ +Command Reference +***************** diff --git a/docs/source/Reference/SystemVariable.rst b/docs/source/Reference/SystemVariable.rst new file mode 100644 index 000000000..f9dbb6d19 --- /dev/null +++ b/docs/source/Reference/SystemVariable.rst @@ -0,0 +1,2 @@ +System Variables +**************** diff --git a/docs/source/Rules/Rules.rst b/docs/source/Rules/Rules.rst new file mode 100644 index 000000000..a5eb5512f --- /dev/null +++ b/docs/source/Rules/Rules.rst @@ -0,0 +1,2 @@ +Rules +***** diff --git a/docs/source/conf.py b/docs/source/conf.py index a30da1fdb..e50230aad 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,6 +16,7 @@ # import sys # sys.path.insert(0, os.path.abspath('.')) from recommonmark.parser import CommonMarkParser +import sphinx_bootstrap_theme # -- Project information ----------------------------------------------------- @@ -80,17 +81,104 @@ pygments_style = None # -- Options for HTML output ------------------------------------------------- - +html_logo = 'ESPEasy/espeasy_logo.png' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +#html_theme = 'sphinx_rtd_theme' +html_theme = 'bootstrap' +html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # # html_theme_options = {} +#html_theme_options = { +# 'canonical_url': '', +# 'analytics_id': '', +# 'logo_only': False, +# 'display_version': True, +# 'prev_next_buttons_location': 'bottom', +# 'style_external_links': False, +# # Toc options +# 'collapse_navigation': True, +# 'sticky_navigation': True, +# 'navigation_depth': 4, +# 'includehidden': True, +# 'titles_only': False +#} + +html_theme_options = { + # Navigation bar title. (Default: ``project`` value) + 'navbar_title': "ESPEasy", + + # Tab name for entire site. (Default: "Site") + 'navbar_site_name': "Site", + + # A list of tuples containing pages or urls to link to. + # Valid tuples should be in the following forms: + # (name, page) # a link to a page + # (name, "/aa/bb", 1) # a link to an arbitrary relative url + # (name, "http://example.com", True) # arbitrary absolute url + # Note the "1" or "True" value above as the third argument to indicate + # an arbitrary url. + 'navbar_links': [ + ("Rules", "rules"), + ("Forum", "https://www.letscontrolit.com/forum/viewforum.php?f=1", True), + ], + + # Render the next and previous page links in navbar. (Default: true) + 'navbar_sidebarrel': True, + + # Render the current pages TOC in the navbar. (Default: true) + 'navbar_pagenav': True, + + # Tab name for the current pages TOC. (Default: "Page") + 'navbar_pagenav_name': "Page", + + # Global TOC depth for "site" navbar tab. (Default: 1) + # Switching to -1 shows all levels. + 'globaltoc_depth': 2, + + # Include hidden TOCs in Site navbar? + # + # Note: If this is "false", you cannot have mixed ``:hidden:`` and + # non-hidden ``toctree`` directives in the same page, or else the build + # will break. + # + # Values: "true" (default) or "false" + 'globaltoc_includehidden': "true", + + # HTML navbar class (Default: "navbar") to attach to
element. + # For black navbar, do "navbar navbar-inverse" + 'navbar_class': "navbar navbar-inverse", + + # Fix navigation bar to top of page? + # Values: "true" (default) or "false" + 'navbar_fixed_top': "true", + + # Location of link to source. + # Options are "nav" (default), "footer" or anything else to exclude. + 'source_link_position': "none", + + # Bootswatch (http://bootswatch.com/) theme. + # + # Options are nothing (default) or the name of a valid theme + # such as "cosmo" or "sandstone". + # + # The set of valid themes depend on the version of Bootstrap + # that's used (the next config option). + # + # Currently, the supported themes are: + # - Bootstrap 2: https://bootswatch.com/2 + # - Bootstrap 3: https://bootswatch.com/3 + 'bootswatch_theme': "cerulean", + + # Choose Bootstrap version. + # Values: "3" (default) or "2" (in quotes) + 'bootstrap_version': "3", +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -160,7 +248,7 @@ man_pages = [ # dir menu entry, description, category) texinfo_documents = [ (master_doc, 'ESPEasy', u'ESPEasy Documentation', - author, 'ESPEasy', 'One line description of project.', + author, 'ESPEasy', 'ESP82xx/ESP32 firmware to connect people with any level of experience to system automation.', 'Miscellaneous'), ] diff --git a/docs/source/index.rst b/docs/source/index.rst index 108bb7015..2dc925f89 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -8,10 +8,25 @@ Welcome to ESPEasy's documentation! .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: Table of Contents + ESPEasy/AboutUs.rst ESPEasy/FunctionBlocks.rst Controller/Controller.rst + Plugin/Plugin.rst + Rules/Rules.rst + +.. raw:: latex + + \appendix + + +.. toctree:: + :caption: Appendix + + Participate/Documentation.rst + Reference/Command.rst + Reference/SystemVariable.rst