From ffd0d26ed321153043a10bdf080ab2387f4e08d5 Mon Sep 17 00:00:00 2001 From: TD-er Date: Mon, 8 Oct 2018 00:00:27 +0200 Subject: [PATCH] [Docs] Added some directory structure and template --- docs/requirements.txt | 3 + docs/source/Controller/Controller.rst | 21 ++--- docs/source/ESPEasy/AboutUs.rst | 2 + docs/source/ESPEasy/espeasy_logo.png | Bin 0 -> 1831 bytes docs/source/Participate/Documentation.rst | 35 ++++++++ docs/source/Plugin/Plugin.rst | 2 + docs/source/Reference/Command.rst | 2 + docs/source/Reference/SystemVariable.rst | 2 + docs/source/Rules/Rules.rst | 2 + docs/source/conf.py | 94 +++++++++++++++++++++- docs/source/index.rst | 17 +++- 11 files changed, 167 insertions(+), 13 deletions(-) create mode 100644 docs/requirements.txt create mode 100644 docs/source/ESPEasy/AboutUs.rst create mode 100644 docs/source/ESPEasy/espeasy_logo.png create mode 100644 docs/source/Participate/Documentation.rst create mode 100644 docs/source/Plugin/Plugin.rst create mode 100644 docs/source/Reference/Command.rst create mode 100644 docs/source/Reference/SystemVariable.rst create mode 100644 docs/source/Rules/Rules.rst 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 0000000000000000000000000000000000000000..3fc1cb4c23c64d3d9e07e08a41f38bcb9d653127 GIT binary patch literal 1831 zcmV+?2iW+DP)I3EY9g$gs7M0F_&ksxyF^4mfuI2q zR0!c@q8<^0A$o$K9!xw)5Q827qbJat#z*2S@qt;;g9l;)qJ&30D35(;WZB)%L+|Lo z&U9DxRQL9F*LNZ_HTC_gep5qN_qW{!2T7U)EC3b(-N3Ct2XKu`KP6T#a0WOG900xm zzA?s(*mhuS8cFH|o&}x+rn%QyX`KRg1FsunPA4^v1tMuO@EouixXMd;)m1<660qGE zbD>qEmOv!U0QLfR`>(Ci`Vm-bj5*ru&89#kbpsy*of#HZWt{<57-RNd`o&{t{~88%676qp0OkPOfWZmw(Ussa7uayoE0Q`T4QTvyUecq@s+F`<(uERu zJQ(BAC#j>c@yi~HNvrdc9*O(PN!nfkkFE7alO&yLvzW9>9K>jib1UF+LQ)M$_qS0< zJF*(Y=s>1b#A87XSZvdoXAJ^tj4>Zrwx3ZEkHs~jqk%l-ItYNLE8@|Oq+e4m)iknR z-gQY@D`})69>1XIkShvIG)fq)=8s0*sW(0!V<-hI|7FFxr$)AOVI4`2rGPc#;nw0ftAl3naks ztagA5${ofs6>p*n14Bv=B*4f>X@CS68Ojw%fRV9WfCLyh$QDSNL9816oUPJcYbct> zkffcGx+PsNX^y1VZ2PbQG9>A-5=>NH9!=*;@jnE?0dl9q zAOei|eiOrZHbAbh97KST+;?Ia&jv_hfJ^~~ZU6IC|CNjv10=_=|(<>g_O&B`N}C8gU~7Il}O>E(vJ zf^q?drSb^M1sD#>Iw%)lI4aAaT!4{6Sq0_F0;3c`xd5XL`3}kj7;VaDP%gmmAYVbb z0K=1f1myw@k7@@0mm2+9=*hGYli>Hs4@*#MapVB{woAbSFg z{A7FB`$UUDtX6>GRW2LDw|LQt+?3PHJoDFo#T zrpsIg;~?jo3@Zwx?E@}%@K|k(`OwkhJz#QD+XVdudRshy#H<}gc zTX`K#tw`a~?$K1Aq%D$S9|t9AzNGKc7=)mly^ct_-NDl+`kNZ3`y%@e%DJwLG`sxq zSQ$S{n(E@);J@C*$Y)TltT6f{-QtE}OdY#y%|cKvS)1LaziBN~C7rf0^AVIQ>&lR# zzpb>o{9sX&)nlc~7?kt5&v@T$+GFdQZDZI@P_E1?qpoM%raiVcBk5d{VVQz*S?s`_ z!W|Yh9!fGy6O^mM%Bbrhw<%AovnR7B`219CbVJ@vC9Z&EZMs|-psv-D~vQAd0go`l76@JxfewbCq5a|Xl}+ZY(2&^9Wo+meM%TV zS$Z6oRI7jR#h8X~WDLW`qbO0GU21&pd3?>wWxp~cX-ngWuT|^A-yyZQ--q0Ta;+5S zu|~y!QP){TCkn^hWlzze?K(+cIre!@mtJp?v?=BT^}99SBWb3j`xMubyZS- z0A0qID)F20x-Ii76O}q{%mTilzM@Uz&vBjZ><_xoug5-8QK6m1x)u+ zUUhT=*ahq`#+*%R>~zvh(bj%GumtD^ZUZ`iDeiTaQs;ovz+vD3@Hw#G7&Btq!M{{= Vczp-GAX)$b002ovPDHLkV1kVqJ3#;d literal 0 HcmV?d00001 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